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^^Without a doubtf the Premiere Resource Editor 
for the Mac OS ... A wealth of time-saving tools,” 

- MacUser Magazine Eddy Awards 

distinct improvement over Apple's ResEdit." 

- MacTech Magazine 

'Every Mac OS developer should own a copy of Resorcerer.'' 

- Leonard Rosenthol, Aladdin Systems 

"Without Resorcerer, our localization efforts would look like a ^ 

Tower of Babel. Don't do product without it!" 

“ Greg Galanas, CEO and President, Metrowerks 

“Resorcerer's data template system is amazing" 

-Bill Goodman, author of Smaller Installer and Compact Pro 

"Resorcerer Rocks! Buy it, you will NOT regret it." 

- Joe ZobkiWy author of A Fragment of Your Imagination 

"Resorcerer will pay for itself many tim^es over in saved time and effort" 

- MacUser review 

“The template that disassembles PICT's is awesome!" A 

- Bill Steinberg, author of Pyro! and PBTools 

“Resorcerer proved indispensible in its own creation!" 

- Doug McKenna, author of Resorcerer 




Version 2.0 



• Very fast, HFS browser for viewing file tree of all volttmes 

• Extensibility for new rentices (CFM plug-ii 

• New AppleScript Diet ^ , pprentice Editor 

■ Mac OS 8 Appearance Manager-sawy Control Editor 

• PowerPlant text traits and menu command support 

• Complete AIFF sound file disassembly template 

• Big-, little-, and even mixed-endian template parsing 

• Auto-backup during file saves; folder attribute editing 

• Ships with PowerPC native, fat, and 68K versions 


rentices (CFM plug-ins) 
pprentice Editor 



New 

in 


Requires System 7.0 or greater, 
1.5MB RAM, CD-ROM 


Standard price: $256 (decimal) 
Website price: $128 - $256 
(Educational, quantity, or 
other discounts available) 


Fully supported; it’s easier, faster, and more productive than ResEdit 
Safer memory-based, not disk-file-based, design and operation 
All file information and common commands in one easy-to-use window 
Compares resource files, and even edits your data forks as well 
Visible, accumulating, editable scrap 

Searches and opens/marks/selects resources by text content 
Makes global resource ID or type changes easily and safely 
Builds resource files from simple Rezdike scripts 
Most editors DeRez directly to the clipboard 

All graphic editors support screen-copying or partial screen-copying 


Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 


Payment: Check, PC’s, or Visa/MC 
Taxes: Colorado customers only 


Extras (call, fax, or email us): 


u-f ciuAii u-sj 

COD, FedEx, UPS Blue/Red, 


All graphic editors support screen-copying or partial screen-copying 
Hot-linking Value Converter for editing 32 bits in a dozen formats 
Its own 32-bit List Mgr can open and edit very large data structures 
Templates can pre- and post-process any arbitrary data structure 
Includes nearly 200 templates for common system resources 
TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 
Full integrated support for editing color dialogs and menus 
Try out balloons, detb’s, lists and pop ups, even create C source code 
Integrated single-window Hex/Code Editor, with patchings searching 
Editors for cursors, versions, pictures, bundles, and lots more 
Relied on by thousands of Macintosh developers around the world 


International Shipping 


Mathema:sthetics, inc. 

PO Box 298 

Boulder, CO 80306-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 


resorcerer@mathe mae sthetics. com 


Ib order by credit card, or to get the lat^t news, bugfixes, updates, and apprentices, visit our website... 


www.mathemaesthetics.com 
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PROGRAMMER'S 

BOOKSHELF 


By Paul E. Seving, Switzerland 


The C++ Programming Language 


Third Edition and 
Special Edition 

A couple of months ago, 
Acldison-Wesley published a special 
edition of the third edition of Bjarne 
Stroustrups The C++ Programming 
Language 21. 'I'he special edition 
features two new appendices that 
my copy of the third edition (9tli 
printing) does not contain. 
However, both a['?pendices are 
freely available from Bjarne 
Stroustrup's home page [3]. And 
except for minor differences that 
exist between any two printings (ch 
erratas [3l), the ctmtents of both 
editions are identicaL 

The book teaches Standard C++ 
and the C++ Standard Librar\% and 
discusses programming techniques 
supported by C++. In my 
experience, it also serves well as a 
reference manuah 

The four main parts of the 
hook— Basic FacilUies, A bsiracdon 
Mechanisms, The Standarcl Library, 
and Design Using C++ — are 
preceded by an introducttiry part, 
Initrjdiiciofy Ala ferial. All the 
chapters contain a section called 
AdiHce where in other books one 
would find a summary. With the 
exception of the first two chapters of 
the last part, all the chapters in the 
main parts end with exercise sectit>ns. 


The advice sections just contain a list of tips (a few 
up to two dozen). Examples are ""Use 0 rather than 
NIJIJA' [1, p. 104] or ‘Avoid type fields'' [1, p. 324]. 
Taken out of context, they appear to be trivial at best, 
but I find them to be quite valuable both while learning 
C++ and in practice. 

Introductory Mai erial 

The introduction consists of three chapters. 

The first chapter is mostly non-technical and gives 
an overview of the book, recaps C++\s history, etc. 
Even though it gives the impression of being 
unimportant, I highly recommend to carefully read this 
chapter. It contains very interesting background 
material on C++. 

The sect^nd and third chapter give an overview of 
the language and the standard library, respectively. 
What is quickly explained in these two chapters is 
explained in (much) more detail in later chapters. 
Readers new to C++ will most certainly not understand 
everything, but that is not necessar^^ Hcjwever, who 
thinks of herself or himself as a C++ programmer can 
u.se these chapters as a refresher course on the one 
hand and as a fitness test on the other hand. 

Basic Faciijties 

The six chapters of parr 1 describe the language 
constructs that support procedural and modular 
programming. These two paradigms are briefly 
explained in chapter 2 only. Therefore, the reader 
shoiid at least be familiar with procedural programming 
and the principle of information hiding. 

Chapter 4 presents the built-in types as well as 
enumerations, dedaralions, and syntjnynis for types 
(typedefs). Cliapter 5 treats pointers and referenc'cs, arrays, 
tmd structures (records). Chapter 6 dlscuxsse.s expressions. 

Continued on page 86 


Paul E, Seving became the 43rd president of tlie United Stales after Florida wasnf able to make up its mind. You can reach 
iiini at paulsevtiK@uhilubAHg. 
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The New ' 
MacHASP USB Key! 


Question: Is MacHASP USB* a 
software security key or a 
sales tool? 

Answer It's both! 

MacHASP USB is the world's first 
software protection key for the 
iMac. It gives you sophisticated 
license enforcement and compre¬ 
hensive protection against illegal 
use... in other words, real security. 

Then it gives you a big seliing 
advantage. 

With MacHASP USB, you can 
license multiple software modules 
and applications. You can instantly 
unlock or upgrade them in the 
field. Plus you can freely distribute 
demos. 

Bottom line: MacHASP USB locks 
out illegal users and unlocks your 


full sales potential - without 
getting in anyone's way. Call now 
to request a Developer’s Kit and 
our newly published guide to USB 
features and benefits. 

*For all USB-equipped Macs running an OS 
with USB support. Fully compatible with the 
ADB version of MacHASP. 

AadcmDliiT ' 

Mact)S 

USA: 1-800-223-4277 
212-564-5678 
Int’l: 972-3-6362222 

www.aks. com/mt 

ALADDIN 

KNOWLEDGE SYSTEMS LTD 


Mac software protection provider. Micro Macro Technologies, becomes part 
of Aladdin, giving its customers even better service from the number one name. 




CETTIlUG 
STARTED - 
lUETWORKiniG 


By John C. Welch 


MacNFS 


Reviewing Thursby 
Unix Connectivity 
Package 


Background 

I'his iiK^nih wc will tiikt* 'a look 
at MacNFS 3 0, from Thursby 
Systems. MacNFS is an NFS client 
that allows you to mount Unix NFS 
shared file systems on your Mac. 
This is a one way sharing, as 
MacNFS does not allow you to share 
your files to Unix users via NFS. 
With OS X looming large, and NFS 
being a key type of filesharing under 
that OS, NFS connectivity for the 
'Classic’ Mac OS is w'orth looking at. 

MacNFS 

MacNFS is a NFS, (Network File 
System) client for any Mac with at 
least a 68030 CPU, Mac OS 7.6 or 
higher, and Open Transport. To 
access Unix NFS shares, or file 
systems, the Unix box needs to be 
using NFS version 2 or greater, 
PCNFSD, (this is the daemon, or 
process that allows MacNFS to log in 
to the Unix box to mount drives) 
version 2 or greater, Network Lock 
Manager version 3 or greater, and 
Mount program version 1 or greater. 
For my tests, T ran MacNFS on a 


variety of G3, G4, and other PowerMacs and 

PowerBook G3s. Unix servers were a mix of Sun boxes 
running Solaris 7, and SGI boxes running the current 
version of Irix, 6.5-X. 

The installation of MacNFS is straightforward, with 
your options consisting of which parts of MacNFS to 
install. The entire package is a User’s guide, the 
MacNFS Chooser extension, and online help, which 
consists of Mac Help files and an Apple Guide file. 
Once you install, you restart your Mac and serialize 
your copy. To initially use MacNFS, you open the 
Chooser, and select the MacNFS icon. You are then 
presented with a dialog requesting your name, 
company, and license number. This is my first minor 
beef with MacNFS, and Thursby in general. The license 
numbers that Thursby uses are some of the more 
complex ones I’ve seen in the Mac market. This by 
itself is not bad until you buy 30 copies of MacNFS, and 
get a page of labels, each with its own license number. 
A single license number for multiple copy purchases 
would be a good idea, especially if you remotely install 
MacNFS on multiple Macs at different locatioas. 

Once you have entered the license number, you 
can then start setting up MacNFS. The initial 
presentation in the Chooser shows you a listing of all 
machines on your subnet that are exporting NFS shares. 
This is shown in Figure 1. 


John Welch <iweldi@aer.com> Ls the Mac and PC Administrator for AER Inc., a weather and atmospheric 
science company in Cambridge, Mass. He has over fifteen years of experience at making computers work. 
His specialtie.s are figuring out ways to make the Mac do what nobody thinks it can, and showing that the 
Mac is the superior administrative platform. 
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FairCom has been providing fast, flexible and scalable database development tools to the commercial 
developer for over 20 years. During this time FairCom has been utilized within countless embedded 
appliances, web server development projects and many vertical market applications. By offering industry 
leading performance, unsurpassed multi-user data availability and a complete transaction enabled database 
Server, FairCom provides the depth and breadth of technology to fit all td' your database development 
needs. Add FairCom to your toolbox today* 


C3I\E FAST ISAM TOOL, 

MANY PLATFORMS 

Every copy of c-trce Pins supports all these platforms: Mac OS, Mac OS X, MK Linux, 

Linux (Intel.,*), Novell Netwam, OS/2, Solaris (SPARC), Solaris (Intel), Sun OS, AIX, HP UX, SCO, 
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c-tree Plus® 

* tftdusffy leading performance 

‘ Seamless cross platform migration 

* Vnsu rpassed mulli-user data a vailahility 

■ Complete source code 

* Fortable ikreading API 

* Thread safe libraries 

* [jOW total cost of owners hip! 

FairCom® Server 

* Powerful multithreaded database server 

* Available for over 25 platf orms 

* Robust heterogenous network support 
- Mix and match clients and servers 

* Multi threaded client support 

* Full transaction processing 

■ Automatic file recovery 

■ Very small RAM and disk footprint 

* Easy installation/conflgu ration 
' Mo DBA required 

* Much more! 


www.faircam.com/mac • USA. 500,S34.8i80 • info@faircam.com 
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[ Setup,^ ] 


^ ApptsTajk 


® Active 
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7.6,2 


Figiire 1. MacNFS Server List. 


Tills list looks like any other serv^er list you would 
see in the Chooser, You have the ‘OK‘ button, W'hich 
alhws you to select the server you want to log into. 
The other button takes you into the MacNFS client 
setup. As you can see in Figure 2, the setup for 
MacNFS is fairly straightforward. 


MldCNFS ! 


m 




- Commonly Used Servers 




> 

idd Server j ! Beinave 


--Create Permtssiorrs - - 

File; R W X Folder; fi w x 

Owner 0130 Owner 000 

Group 0D0 Group 0D0 

Other 00 3 Other HDa 



□ Askfprvolume name 
0 Browse Services 

□ Disable auto-refresh 

□ Disable Desktop Database 
0 Show hidden UNIX files 

□ Translate End df Line 
0 Performance 

[ Bk » { DtJlTerSize 
[is : * I DetransmitTimer 
[is t\ Droadcast Timer 


[ Info.,. I f Cancel ] [( Save ]j 

'■ ■ ‘ v 4 l , J'Cg!XWg? y 


Figwre 2. MacNf'S Client Setup. 


The options allow you to configure the liasic 
behaviors cjf the client. For the most part, the default 
options w'ill work. Most administrators will want to 
ct)nfigure the create permissions, which control iiow the 
NFS filesystems apply file access mles tf) files created 
using the MacNFS client. The 'Show hidden IINIX files' 
option controls the vLsibiiity of Unix files, which are 
normally configuration files, and not view^alile by non- 
ad minislrators. 'Translate End of Line' ainomalically 
handle converting Unix line-end characters to the Mac 
line ends. The Info.,/ button shows the statistics for the 
client, and allows you to change the license code for that 
client if needed. Once you have made the necessary 
changes, clicking 'Save' commits tho.se changes, and 
returns you to the sender list. 


Picking a server to access disks from is similar to 
doing it via AppleShare. You select a server, and either 
double-click, or click OK: You are then presented 
with a login screen, shown in Figure 3. 



Fig u re J. Log i n Sc ree n. 

The login has one unique feature, that being the 
'Security:' pulldown menu. This is a listing of all visible 
servers that are running the PCNFSD aLitheiiticatit)n 
daemon. This allows the u,ser to authenticate against 
different seiwers if the primary is down, or a specific 
set of NFS .shares can only he auiheniicated by a 
specific server. Also, the user does not have to 
authenticate to ifie same serv^er that they are trying to 
mount, so a single authentication server can be used 
for all NFS shares. 

Once the user has authenticaied, a list of default 
sflares for that server is disptayecL This screen, in 
Figure 4, is where the user selects ihe share(s) they 
wish to access, and to set share-specific options. 


I MacNFS Export List! 


gaea.aer.com 

Se lect the veiumes you want to mount; 


m 


f^/home/tm 

Q/home/sy* 

r"l/hoiifie/ivs.^cwelch 

Q/opt 


□ 

□ 

□ 


Checked Items ( 1^ )wlll be opened at 
system startup time. 






[ Bk i ^ j Buffer Siie 
[is ' ^ j Retransmit Tinier 


□ Translate Efid of Line 
0 Performance 


[ Options I [ Add Path j [ Remove \ \ Cancel j | OK | 

□ Disable Desktop Database □ Disable auto-refresh 
Ask for volume name 0ShowhiddGn UNfxnies 


Figure 4. Defcmll Shares. 
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This screen has many of the san^e options as the 
main settings screen, l^ut any options set here, only apply 
to a specific share or shares. Like other network clients, 
the user can set cenain shares to automatically mount cm 
system startup, Ujifortunaiely, this version of MacNFS 
does not allow for the KeyCiiain to l:ie used to store the 
passwords for these shares. The *Optjojis’ button toggles 
the options .section of the screen on or off^ (shown ON 
in Figure 4j The 'Add Path/ button brings up a dialog 
that allows tlie manual entry of a share that does not 
appear in tlie window. These shares must be entered 
using IJnLK path conventions, and the entire path must be 
entered manually. An ability to brow'se to the desired 
share would make this option easier to u.se, as Unix patlis 
can he quite coinplicated. The 'Add Path’ dialog is shown 
below in Figure 5- 


I MacNFs Security i 


Connect to the server 
"ga ea.aer.com" as: 


User name: 

Password: 

Security: 


gaea.aer.com 


J 


Cancel ] 1^0 


Figure 5. Add Fait Dialog. 


Once the share has been selected and mounted, it 
behaves as any other network share would. Since Unix 
does not use dual streamed filesystems, MacNFS keeps 
the resource fork information in a separate file, that 
has the same filename as the data fork, but preceded 
by a percent sign. File access and usage is as fast as the 
network allows, but in general, it is speedy over 
10Mbps Flhernei. 

'fhursby has done an excellent [ob in making 
MacNFS easy to use on a wide range of Macs. Although 
there are some minor issues with the manual path 
addition process, lack of KeyChain integration, and the 
.serial numbering process, these are relatively minor 
quibbles, and are not bad enough to cause second 
thoughts about using MacNFS., fil 
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CARBON 

DEVELOPMENT 


By Eric Simenel 


Carbonization 101 


Easier than you might think 
and so rewarding 

The Benefits of Carbon 

A beta version of Mac OS X lias jiLSt been released to the 
public and a final version should be released in early 200 L 


Classic 


Cocoa 


Java 


Carbon 

Mac OS X 


f igure /* Mac OS X applications. 


Four different kinds of ap[')lit:aiicjns, shown in Figure 1. can 
am on Mac OS X: 

1 unmodified Mac OS applications currently running on 
Mac OS 9 or earlier, will run in the Classic 
environment. The User Experience will be the same as 
the one provided with Mac OS 9, and if one of the 
applications running in that environment encounters a 
serious problem, it may bring down the whole 
environment and thus any other application running in 
that environment. 

2 Java applicationsj developed using only the JDK and 
companion libraries. 


3 Cocoa applications* developed in either java or 
Objective-C (possibly mixed with C/C++), and using 
the Cocoa frameworks, 

4 and, last but not least, Carbon applications which are 
slightly modified Mac OS applications. 

Each of the last three kinds of application, Java, 
Cocoa, and Carbon, all run as separate processes in their 
own protected memory area. If any of those applications 
encounters a serious prolilem, it won’t affect the others, 

Uie benefits, then, of Carbonizing an application 
should be apparent; for the cost of a few hours or days of 
work, you get a much more robust and impervious 
application that your users can run without problems. 
Another advantage is that a carbonized application gives 
you the Aqua theme user interface on Mac OS X, 

CarlD<jn being [^resent, diroLjgh the installation of CarbonLib, 
on Mac OS 9, S,6, and 8.1, a Cartonized appliatdon, as a single 
binary, can run on aH Mac OS fmm 8.1 to X. 

The Scope of Carbon 

M{>st applications and some plug-ins can be 
carbonized successfully. Exten.sion.s (INITs), Control 
Panels (edev), and drivers of any sort cannot be 
carbonized since they don't run on Mac OS X and the 
main goal of Carbon is to provide an easy transition for 
developers from Mac OS 8 and 9 to Mac OS X, 

Which version of Carbon should be used? 

The version of Carbon that you choo.se depends on 
your goals and the configurations that you are targeting. If 
you want the maximum Mac OS coverage, u.se only 
Carbon 1.0.4 APfs which are supported from Mac: OS H. 1 
to Mac OS X* Carbonllb TO.4 gives most of the Toolbox 
APIs, plus the Control, Window, and Menu Properties, 
Navigation Services, the Core Foundation APIs, and 
Carbon Printing TO. If, when carbonizing, you find that 


Eric Simenel simcnd.e#apple.com is a sfitware engineer in Applets DTS (Developer Tedinical Sypp(>rt) team, lie Is currently supporting Mac OS 9 and Caiixin. 
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// Like most Mac developers, 

// I easily spend 12 hours 

// staring at line after line of C++ code in tinv, 9 point Monaco. 

// Sometimes it makes my eyes feel like they're on fire. 

{ 

So the last thing I need is some 
fuzzy monitor that adds to my headaches. 

} 

/*•*••• begin excitement ••*•••/ 

// That's why I’m $0 jazzed about this SGI monitor. 

// Its ultra-high resolution = 1600 x lozzj and dpi = no, 

// giving me razor-sharp contrast. 

// And the high refresh rate is 
// perfect for poring through lines of code. 

// At first, I was amazed at the clarity, the fine details that emerged. 

1 

It wa^ like seeing things for the firct time. 

I 

// Later, though, I learned to appreciate the wide aspect ratio (= i6:io|. 
// with a generous 17.3 inches of viewing area. SGI’s 1600 SW 
// lets me have all my documents viewable at once, and it's 
// a flat panel so it fits on my desk with room to spare. 




// From the moment I saw this thing I was hooked. You will be, too. 

i 

Especially when you find out 
how affordable it is. 

// ^ Check it out. 


/•••••• end excitement 




Michael Whittingham 
V.R» Engineering 
Wired, Inc. 













you are missing a desired functionality, check if it is 
provided in the Carbon 1.1 APIs which give you access to 
Appearance 1.1, Carbon Events (which offer an 
alternative to patching the Toolbox), the new 
Data Browser control, ATSUl, URL Access, Keychain, 
FontSync, XML, liTMLRenderingLib, and others. Choosing 
the Carbon 1,1 APIs will restrict your target configurations 
to Mac OS 8.6 and above. 

Note; Carbon on Mac OS X, and its companion 
CarbonLib for Mac OS 8 and 9, are not a closed API but 
an ongoing development, Future Apple technologies 
might be delivered only through the Carbon APIs, 

The Carbon Porting Process 

Let's examine the nuts-and-bolts to see how porting 
to Carnon can be done. The goal of this articie is not to 
be a rewrite of the “Carbon Porting” document w'hich can 
be found in the Carbon SDK (see the bibliography at the 
end of the article for useful URLs), but ratlier a step-by- 
step guide based on DTS Engineers' experiences during 
various Carbon Porting lab events with 3rd-party 
developers at Apple. 

Tills is not just a bunch of recipes, aldiough you may find 
them very useful, but ratlier a metlicxiotogy to apply when you 
encounter a problem not yet covered in any documentation, 

Estimating how much work will be required 

Of course, the amount of work depends on the size 
of the source code and the number of unsupported APLs 
in your source code. Experience in the Carbon Porting 
labs tells us that most developers can successfully 
carbonize 80% or more of their applications in the 3 to 5 
days of that event. 

CarbonDater is a tool which may help you quickly 
determine the amount of work to be done. An example of 
a Carbon CompaLibiiily Report is siiown in Figure 2. 

Carbon Compatibility Report 

^poct fox: T^$ixvice3l<ailJBdn3de livpDn 

Fib CtH«ir 7777 UMFUf 1.3 

FUf Ty^z AP?1. IM.1i oar 


Siuiiniary 



Figure 2* The Carbon Compatihiiily Report. 


The Carbon Compatibility Report also provides a 
fairly detailed analysis and some suggestions as to how to 
replace unsupported APLs (Figure 3) and the kinds of 
modifications you will have to make in order to be 
Carbon-compliant (Figure 4). 


Llri£upfjQ[|:ed 


MtDialags id not supported m Oairbon. Thiede is no n£ed to imtblize the Dialog 

Mccoager becaisae the ahaned libjar? ia loaded esd needed. Hotaveileble in 

Carbon. 

Figure 3- Unsupported APT 

In Carbon, yon cannot pa35 yow o w a^iage In to ^ wStorag» paraineter. 

AvaiJabla in Nac OS 8.1 and later 'vhan Carbon 1.0.2 or later is present. 

Figure 4, Modified APT 

Another w ay to estimate the necessary amount of time 
is to plunge right into the Carbonization process; the first 
compilation will give you an idea of the extent of the 
work to be done. 

First things first 

As the “Carbon Porting Guide” suggests, it's best to 
update your project to the latesi Universal Headers first. If 
you're interested in Carbon 1.0, then use the Universal 
Headers 3 3 2, but if you're interested in Carbon Tl, then 
use the Universal Headers 3.4. If you are developing w ith 
Code Warrior, !x" careful to follow the instructions (from 
your CodeWarrior User’s manual) and update any pre¬ 
compiled headers if youVe using them. 

The next step depends on the size of your project and 
the way you prefer to develop. You can either follow' all 
the steps described in the “Carbon Porting Guide” (w'hich 
is preferable if your project is large), or follow these 
instructions (w'hich assume you are using CodeWarrior, 
any version after and including Pro 2): 

• first, clone your existing PowerPC target, 

• second, add the preprocessor command #define 
TARGET.API. MAC_CARBON 1 to the beginning ol your 
project’s prefix file (if you already have a prefix file, tlien 
duplicate it, add the preprocessor command in one of 
them and use this one for your Carbon target), 

• and third, remove all Apple stub libraries such as 
Interface Lib and any otJiers that you might have 
needed in your project such as AppearanceLib, 
WindowsLib, etc., and add the CarbonLib stub instead. 
You can keep non-Apple libraries such as “MSL 
RuntimePPC.Lib”, “MSL C.PPG.Lib”, etc. 
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Move to digital.forest. The leading Internet Service 
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your ISP. You'll find it with digitaLforest. We're the proven provider of 
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If you are using Jiny other libraries^ then you will 
need to determine (the PEF Viewer utility can help you do 
that) if the code they contain is importing any symbols 
from InterfaceLib or any of those Apple libraries at 
runtime. If that's not the case then they should be safe to 
use as is, but if they are , then those libraries will have to 
be carbonized as well 

After yoirre finished with those 3 steps, which 
shouldn't take you more than a few minutes, then attempt 
your first build. 

You will get many, perhaps thousands, of errors. 

Luckily, 80% of them, if not more, are repeats and just 
illegal access to Toolbox structures which are now' opaque 
or illegal type usage (DialogPtr, WindowPtr, and GrafPtr are 
now' 3 different pointer types and can't be used in place 
of each other). Addressing those errors Is simple but 
tedious, and it just lakes time. There are 2 different ways 
to fix those errors, one involving the Carbon Accessors, o 
library, and the other one involving conditional 
compilation. For instance, the following extract, wiiich 
should be quite common in your source code: 

WindowPtr theWind: 

SetFort(tbeWind): 


is going to generate the compiler error: 

Error; 

cannot convert *OpaqueWindowPtr *' to 'OpaqueGrafPtr 


You can either change the source code to 

SetPortWindowPort(theWind); 

and add the CarbonAccessors.o library to your non-Carbon 
targets in your project or change the source code to 

#if tTARGET_API_HAC_CARSON 
SetPort(theWind): 

SetPortWindowFort(theWind): 

■//end If 

and you don't have to add the library. 

The advantage of the former solution is that the 
source code is more readable but your non-Carbon 
application is going to grow hy about 60K, whereas the 
advantage of the latter is that your non-Carbon 
application stays rigorously the same, but you will have 
to add a lot of those #if fTARGET_APLMAC_CARBON lines 
in your source code w^hich can also look like: 

#if !TARGET_API_MAC_CARBON 

yLocation = theWind-YportRect. bottotn-10 ; 

//else 

Rent thePortRect; 

GetWindowPortBounds(theWlnd, fifthePortRect); 
yLocation = thePortRect^bottom-10j 
//end if 

It's your choice. 


Finding out Carbon information 

The best way to find out is to apply the following 
methodology: in the previoii.s example, you tried to 
access the portRect field of the WindowPtr theWind. This is 
doubly illegal because the variable theWind is a WindowPtr 
and not a GrafPtr, and also because both WindowPtr and 
GrafPtr are opaque structures anyway. So the obvious 
solution is to look at the Graf Port structure definition in 
QuickDraw,h and there you will see that it changed to: 

struct GrafPort t, 

short device ■ /* not available in Carbon^/ 

BitHap portBits; /* in Carbon 
GetPortBltMapForCopyBits 
or IsPortColorV 

Rect portRect: /* in Carbon Mat Get/SetPortBounds*/ 


and if you look for GetPortBounds you will find it at the 
end of QuickDraw.h in the /* Getters V section: 

EXTERN_API( Rect 

GetPortBounds(CGrafPtr port, Rect * rect): 

So now' you know how to get the portRect out of a GrafPtr 
(or a CGrafPtr, both are equivalent in Carbon since the 
structures they point to are opaque), bur what you have is a 
WindowPtr. Again, since the port of the window is in fact a field 
in the WindowRecord structure you just open Mac Windows, h 
and you look at the WindowRecord (or CWindowRecord) 
.structure definiticm and there you wall see dial it clianged to; 

struct WindowRecord { 

Graf Port port; f*" in Carbon use GetWlndowPort’*'/ 
short windowKiud; i*' in Carbon use Get/SetWlndowKlnd'^/ 

i : 

And if you look for GetWindowPort you will find it at 
the end of Mac Windows, h in the /* Getters 7 section (do 
you see a pattern here?): 

EXTERN_API( CGrafPtr ) GetWindowPort(WindowRef 
window): 

Don't woriy^ about the WindowRef type which is the same 
as WindowPtr (defined in QuickDraw.h tor practical reasons). 
So you could write: 

//.if !TARGET_APr_MAC_CARBON 

yLocation = theWind - !>portRectbottom -10 ; 

//else 

Rect thePortRect: 

CGrafPtr theWindowPort: 

theWindowPort "= GetWindowPort (theWind) ; 

GetPortBounds(theWindowPort, ^thePortRect): 
yLocation - thePortRect.bottom-10: 

//end if 

but, in order to simplify and reduce the coding, Apple 
also provided a direct GetWindowPortBounds call that you 
also find at the end of MacWindows.h: 

EXTERN_API( Rect *) 

GetWindowPortBounds (VlindowRef window. Rect * 
bounds): 
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so that’s why you can write the shorter code shown 
in the previous section. Apple provided those shortcuts 
for the most common usage. 

Since the GetWindowPortBounds call (like the others) 
returns the same Peer as being passed as [he second 
parameter, you could even write: 

#if ETARGET,API_MAC_CAREOfr 

vLocation = theWind->portRect,bottom-10; 

Rect thePortRect: 
yLocation “ 

GetWlndoitfPortBounds (theWind , firthePortRect) - 
>bottom-10: 

#endif 


or even, if you keep a global scratch variable Rect 
gTempRect around which will be used for such operations 
you could write: 

f !TARGET_AP r_MAC_C ARBON 

yLocatlon ^ theWind->portRect.bottom-10: 

#else 

yLocation = 

GetWindowPortBounds (theWind * ^gTempRect} ->botton]- 

10 : 

#endif 

Again, it’s your choice. 

Sometimes, the comments provided in the Header 
files for Carbonization advice are not on the same line as 
the information you’re looking for, but usually they’re not 
too far away. In the following case for example: 

GtafPtr currentPort; 

GetPort(fiicurrentPort); 

EraseRect(&currentFort ->port Rent}: 

InvalRect {StcurrentPort- >portRect) : 


will bring your 

Error : undefined identifier ‘portRect" 
SampleWindows . cp line 33 6 EraseRect (£fcur rentPort- 
>portRect): 

Error r undefined identifier 'InvalRect* 
SampleWindows . cp line 337 InvelRect (iicurrentPort- 
>portRect): 


The incorrect usage of portRect w'lll be fixed by a 
simple call to GetPortBounds as previously but wliat about 
InvalRect? A search for InvalRect (in MaeWindow^s.h) will 
make apparent that we now^ have: 

#if CALL„NOT_IN_CARBON 

EXTERN_API ( void ) InvalRect (const Rect ■* badRect) 
OfJEWORDlt^LINE(OxA928) : 

#endif CALL_NOTJN_CARBON 

so w^e have to look around and we will see that for 
this call as w^el! as for InvaIRgn, ValidRect, and ValidRgn, 
w-e have a comment above which says: 

r 

These aren't present in Carbon. Please use the InvalWindowRect, etc, 
njutines 

below instead. 

V 
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So we will diligently replace the illegal code with: 

Rect thePortRect; 

GetPortBoundsCcurrentPort, &thePottRect): 

EraseRect(SrhePortRect); 

InvalWindowRect(GetWindovFromPort(currentPnrt), 
SfthePortRect} : 

You will note that we also used the utility function 
GetWindDwFromPort which you can find in MacWindowsdi 
as well. 

What happened to my qd? 

The global variable qd has been removed so if yt>u 
had been using some code like: 

Dra^WindowttheWind. theEvent->where» 

&qd,screenBits »bounds ): 


is that tliey wished to extend tlie Toolbox structure vvitli 
their own fields, and to lessen heap fragmentation. Since 
those structures are opaque, this is no longer possible. So 
you will have to modify such declarations: 

Note: All error-checking code has been removed from 
the sample code extracts present in this article so that the 
modifications you have to apply in order to Ca^bo^i:^e are 
more evident. Real code would need error-checking,,. 

typedef struct 

( 

WindowRecord theWind: 

OSType theSignature: 

GWorldPtr theGWorld: 

T My Wind. ‘MyWlndPtr: 
in 


then, after looking for screenBits in QuickDraw.!! and 
finding the relevant comment, you will have to write: 

Rect bounds; 

#if !TARGET_API_MAC_CARBON 

bounds ^ qd*screenBits,bounds: 

#else 

BitMap bmap: 

GetQDGlobalsScreenBits(&bmap): 
bounds = bmap.bounds; 

#endlf 

DragWlndow (theWlnd * theEvetjt-^where . ^bounds) : 


What happened to my InitGraf and other Toolbox 
Managers Initialisation calls? 

Most of them are now just unneeded in Carbon so 
you can just conditional-compile out InitGraf, InitFonts, 
InitWindows, InitMenus, TEInit, and InitOialogs, Ycju must 
still use InitCursor. Typical initialization memory^ schemes 
such as the manipulation of the heap limit (SetAppILimit 
and GetAppILimlt) as well as MaxAppfZone are alst) 
prtshihited in Carbtm. 

For obsolescence reastsns, the support for Desk 
Accessories is no longer required in applications so 
SystemClick and Open Desk Acc have also been remcjved 
from Carbon. 

So is it just searching, Ending, and replacing? 

Although at least 80% or more of the errors you will 
get at the first compilation will indeed be no more 
problematic than that, still it's not going to be that simple 
for the remaining 20% or less. 

First you have to deal with the modified calls such as 
NewCWindow (and NewWindow, NewDialog, and 
NewColorDialog as wc\l for die same reason) which does not 
accept a storage parameter anymore. Unfortunately the 
compiler will not alert you that such calls are going to fait 
although you will get a null return value from the call so if 
you have a gc3txl error-checking code yt)u will easily detect 
the problem at runtime rather than crashing. The main 
reason developers w^ere passing a storage as first parameter 


typedef struct 

[ 

/Hf ! TARGET_AFI_HAC_CARBOK 
WindowRecord theWind; 
#else 

WindowPtr theWind: 

#endif 

OSType theSiguature: 
GWorldPtr theGWorld: 

i MyWind, *MyWindPtr; 


and change from: 

wind =“ CMyWindPtr JNewPt r [sizeof (MyWind)) : 
if (wind !- OL) 

I 

wind->theSignature “ kSig: 

NewCWindow(wind * firtBounds* fName, 1. 

noGrowDocProc. (WindowPtr)- IL. 1* OL): 

T 


to: 

wind = (MyWindPtr)NewPtr(sizeof(MyWind)); 
if (wind i- OL) 

I 

wind->theSignature ^ kSig: 

Hf ! TARGET_API„MAC_CARBON 

NewCWindow(wind. Bounds, fName♦ 1, 

noGrowDocProc. (WindowPtr)-IL. 1, OL); 

#else 

wlnd->theWind = NewCWindow(NULL, ^rBounds, fName. 

1 , 

noGrowDocProc, (WindowPtr)-IL, 1, 

(long)wind); 

#endlf 

7 


and you can still extract your My Wind structure 
location from the ref Con value of your WindowPtr. If you 
were already using the refCon field to .store some other 
information, then you can keep that information in llte 
structure My Wind instead. Another solution is to use the 
new functions SetWindow^Property and 
GetWindowProperty which enable to attach tagged 
information to any window. 

Another likely moclilk!ition you will hiive to make is the 
control list walk-tlirough. Previously you could just start from the 
controlUst field of tlie struauie WindowRecord, but of course tills 
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field is no longer accessible in tlie opiique staicture and there are 
no accessor fLinction to retrieve it. In order to get the first control 
of the control list of a window, you will have to modify your 
ccKle like tliis: 

// window creation with NewWindow, or NewC’Window^ 

II or CreateNewWindow (preferred...), or... 

#if TARGET_API_MAC_CARBON 

ControlRef theRootConurol: 
if {theWindow != NULL) 

CreateRootCoxitrol (theWindow* ^theRootControl} : 

#end±f 


and later: 

Hf !TARGET_API_ftAG_CARBON 

ControlHandle theControl = [ControlHandle) 

( ( (WiiidowPeek) theUlrkdow) - )*controlLlst) : 
while (theControl 1= NULL) 

/felse 

UIiit-16 nutnChildr en , index; 

ControlRef rootControl, theControl; 

GetRootControl(theWindow » ^rootControl); 

CountSubControIs (rootControl, SinumChildren) ; 
for (index ^ ntimChlldren: Index >■= 1: Index—) 
f^endif 
< 

#lf TARGET_API_MAC_CAREOK 

GetIndexedSubControl[rootControl. index. 
f<theControl) ; 

/jl'endif 

//do something with theConiroh 

// you can even dispose it since we re doing a reverse iot)p 
#if tTARGET_API_HAC_CARBON 
#if DISROSINGCONTROL 

theControl = (ControlHandle) 

(((WindowPeek)theWindow)-icontrolList); 

//else 

theControl = (‘theControl) - >nextControl: 

//end 1F 
//end if 
J 

If you didn't acid support fcjr die Navigation Services, to 
l eplace tiie use of die Standard File Package, now is die time 
since Cartxin dtx;s not support die Standard Pile Faekage. 

Another wlioie .section of llie traditional Macintosh 
Toolbox, the Scrap Manager, has also been revised in 
Carbon, Most applications use the Scrap Manager routines 
in a fairly straightforward way and the aiiKiunt of 
modifications you may have to apply may not be much 
more complicated than the following. 

For copying: 

//if !TARGET_APT„MAG_CARBON 
ZernScrap(): 

//else 

ScrapRef scrapRef; 

CJearCurrentScrap() ; 

status = GetCurrentScrap (iiScrapRef) : 

//end if 

#if 1TARGET_API_HAC_CARB0N 

PutScrap(hyteLength. ’utxt^, *hUnicodeText); 

//else 

status = PutScrapFlavor(scrapRef. ‘utxt*. 

kScrapFlavQrMaskNone, byteLength, *hUnicodeText); 
//endlf 


And for pasting: 

//if fTARGET_API_MAC„CARBOn 
LoadScrap(); 

//else 

ScrapRef scrapRef; 

status — GetGurrentScrap{&scrapRef); 

//eudlf 

//if [ TARGE T _A PI _MA C_C ARB ON 

long offset, byteLength = GetScrap(NULL, 'utxt*, 

^offset): 

//else 

long byteLength: 

status = GetScrapFlavorSixe(scrapRef♦ 'utxt'* 
£(byteLength) : 

//end if 

if (byteLength <= 0) return; 

//if \ T ARG E T_ A PI _KA C_C ARB ON 

Handle bUnlcodeText = NewHandle(0): 

GetScrap(hUnicodeText, ^offset); 

//endif 

// let's grab the text from the scrap 
UniCharCount uTextLength - byteLength / 
sizeof(UnlChar) ; 

UniCharArrayPtr theUnicodeText = 

(UnlCharArrayPtr)NewPtr(byteLength); 

//if tTARGET_APl_MAC_C ARSON 
HLock(hUnicodeText): 

BlockMoveData('hUnicodeText, (Ft r)cheUnlcodeText, 
byteLength): 

//else 

status = GetScrapFlavorData,(scrapRef H 'utxt', 
^byteLength, 

theUnicodeText): 

//endif 


Almcxst tliere since we slK>uld just conimcni out all the 
printing code for now. The Priming Manager has licen revised 
also in Carlx)n and in such ways that it could lie the only subject 
of anotlier MacTech article by itself, so we’re not going to deal 
with dial in this article. 

Patience and lalxir will get you to a point where you no 
longer get any compilation enors. 

Bui now you’ll see link errors. 

Maylie some will loe due to Toollxix Cidls present in the 
headers but missing in the Carbon!Jb shared library (this is still 
a w^ork in progR-?ss), but most of the errors will come from the 
u.se of MSL (MetroWerks Standard Libmiy ). Ycju will either have 
to use tile updated for Carbon vei'sk>n of MSL from MetroWerks 
(wliicli is part of CodeWanior Pro 6 wliicli als() conhiins a fully 
orbonized version of PowerPkint) f>r get rid entirely of any 
defiendencies on this package. 

Again, jititience and latxr will gel you to a point where you 
no longej get any link errors. 

And yc>u should liius be able to test your application on Mac 
OS 9 (recommended for the first runs), and it should run line 
;iiltliough you may have to incxease the memory partition 
(resource SIZE ' id -1), 

Depending on the version of CarhonLib you’ve been 
developing against, yoit can also test the tunning of your 
application on 8,6 and 8d, 

But the real test will of course lie the running on Mac OS X! 
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Running on Mac OS X 

If you just launch your recently carbonized application on 
Mac OS X, you may not see a single difference in either behavior 
c}r even appearance with your application running on Mac OS 9. 
The mcxst probable cause is that you're in fact running your 
carbonized application in the Classic environment] If you don’t 
see your application interface using the Aqua theme user 
interface, then you are rurming in die Classic environment. In 
order for your application to be run as a Carlxsn Application, and 
thus in Its own memory-protected space and with the Aqua 
theme user interface, you have to let Mac OS X know about the 
faa that you did your job and carbonized this application. You 
do tliat by adding botli a ‘carb’ resource widi id 0, tlie content 
does not matter, and usually youU just set a single byte as 0, and 
adding a 'plsf resource, also witli id 0, which contiins die XML 
representation of die application's property list. If those 2 
resources are present in your application then Mac OS X will 
launch your application as a Carbon process with all the 
advantages that come with it. 

Note: If ycju have been following the suggested steps 
described above, you should have at least 3 different taigecs for 
your project: debug-CIassic, non-debug-Classic, non-debug- 
Carbon. Your may have more.*. Since all those targets can mn 
on Mac OS X, eidier being launched in the Classic environment, 
or launched as a Carbon process, it might useftil to be able 
to identify at Rjntime, with certainty, which target you’re 


crirrendy running. You could use die following routines (or 
adapt them to your needs) to achieve identification: 

Boolean IsThisXO 
[ 

long response; 

OSErr err = Gestalt(gestaltSystemVersion. 

^response): 

return C(err == noErr) && (response >= 

OxOOOOOAOO)); 

I 

Boolean IsThisAquaO 

I 

long response: 

OSErr err = Gestalt(gestaltMenuKgrAttr, ^response): 
return 
C 

(err = noErr) && 

((response 6 g.estaltMenuMgrAquaLayoutMask) 1 = 

0 ) 

): 

1 

void DoAboutBox() 

I 

Str255 theStr, theSrr2. theStr3: 

//if _option (sym) 

sprintf ((char *)theStr2, "'Debufi Version"): 

//else 

sprintf((char *)theStr2* "Final Version"): 

//end if 

//if TARGET_API_MAC_CARBON 
if (rsThisAquaO) 

sprintf[(char •JtheStrB, "Carbon Aqua"): 
else 

sprintf ((char ‘)theStr3. "Carbon Platinum"]!: 

//else 
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sprintfC(char 'JtheStrB. “ClaESic"): 

#endif 

sprintf((char ‘)&theStr[X], %a, Xs'\ 

(char ‘)theStr2. (char *)thaStr3» DATE _TIME ) : 

theStr[0] = strlen{(char *)5ftheStr [1]): 

ParamTaxr(theStr, **\p*', Aleri:Cl28, OL); 

] 


When amning on Mac OS X, you will notice that some 
system menus have changed and some menu items liave 
moved< One imporrant cliange is that the Quit menu item is 
now in the Application menu (which replaces the Apple menu 
of Mac OS 9 and prevloiLs). You are no longer supposed to 
have a Quit menu item in your File menu. 'Fhat also means, by 
the way, tliat you need to liave a QuitAppleEventHandler routine 
since this is the way that Mac OS X will infomi your application 
dial die user wants to quit it. You are not supposed to add die 
’"desk accessories'’ (wliich liave not lieen true desk accessories 
ibr a very long time anywTiy) in die Apple menu either. 

So your menu initializatkin and installation routine 
should look like: 

Handle menuBar = GetNewHBar(kMainMenuBar}: 

SetMenuBar(menuEar): 

DlsposeHandle(menuBar); 

(Hf TARGET_API_MAC_CARBON 

if CisThlsAqua ()) // removing Ibe QuiX menu ilem and the 
separator line 
f 

MenuHandle menu = GetHeniLHandle(kFileMenu) ; 
DeletaHenuItem[menu, kQultHenuItem); 
OeleteHenuitiEiii{mEnu* kQuitMenuItem■ 1) : 

//else 

AppandResHerm (CetMenuHandle CkAppleMenu). ‘ORVRO : 
//end if 

DrawMenuBar C): 


And with dial line-tuning achieved, you are pretty much 
done* You will still have to thoroughly test your application 
on all Mac OS versions iFs supptJ.sed to run on, hut the job is 
no more complicated dian described here fwdth the exception 
of priming which has to lie rewnUen)* You may encounter 
some mysterious behaviois and tlie most frequently reported 
is that the drawing in one of your windows is not happening 
anymore (typically .some kind of animation)* The mosx likely 
reason For that is that you are drawing in that window outside 
of its update routine and since windows are double-buffered 
on Mac OS X, you just keep modifying the bits of the 
offscreen and nothing happens in the window^ on the screen. 
Carhrai moves the bits from the offscreen to the window at 
tile end of die update routine and in some otlier conditions, 
but not in tliat case, so you will have to add a bit of tweaking 
there as well. There are 2 ways to achieve dial tweaking, but 
only one is recommended. QuickDraw , h provides 3 new^ APIs 
(QDIsPortSuffered, QDIsPortBuffarDirty, and QDFlushPortBuffer) 
w hich can be used that way: 

InltTheCircleO ; 

for (i=si;artingMouth : i<—endingHonth ; 1++] 

I 

UnsignedWide stattingTime, endlngTime; 

Mirroseconds(SstartingTime); 

UpdateTheCircle(i); 


on Mac OS X, drawing is double-buffered by defaulcV 

//if TARGET_API_MAC_CARBON 

if (QDlsPortBuf f ered {(CGrafPtr) ctirPort)) 

QDFlushPortBuf fer ((CGrafPtr) curPortNULL) ; 

//end if 

do fMlcroseconds (fisendlngTiine) : I ’while 

(ComputeMicros (SfStartingTlme, ^endingTime) < 
kAnimatlonDelay): 

} 

TermTheCircle C); 

Tlie odier way, which is not recommended, ts to add the 
kWindowNoBufferingAttribute attribute to the WmdowAttributes 
parameter you pass to CreateNewWindow. In that case, the 
window^ will not t>e double-buffered so all drawing will be 
directed to tlie window, but you disrupt the normal updating 
meciianism of the Window Server and, for instance, if you 
move such a window, you may leave undesirable graphical 
aitifacts on your screen. 

Conclusion 

If you have more than one application to carbonize, we 
advise you to start w ith the most recently developed first since 
it w^ill he the easiest to carbotiiEe. It should already be u.sing 
a recent version of the Universal Headers and shouldn’t do 
icx;> many of the various no-no’s no longer available in 
Carbon, Going back in time, carbonizing older and older 
applications, you will find that the previous experiences will 
help you to overcome the difficulties arising from carbonizing 
C3ld ccxle. But the methodology remains the same: 

1) use at least the Universal Ileaiders 3.3 2 

2) For each error, refer to iliat routine or that structure in 
the appropriate header and read the Carbonization 
comments which are sure to be found around. 

If for any reason you are at a loss as to what to do or 
how to do it, then you’re more than welcome to join and 
participate in the Carbon Development mailing list that you 
can join by Sending an email to <reqLiests@sam.apple. com> 
with “subscribe carbon_development" as the email’s 
message* The Carbon Development mail list is restricted to 
discussion of Carbon development issues. 

If you still can’t find satisfactitin w hen parheipating in the 
list, you can address your question to <dts@apple.com> but you 
need to Ixe a member of our programs in oider to do tliat. 
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WEBOBJECTS 


hy Sam Krishna and Patrick Taylor 


Throughout this series we've asserted that programming 
in WehObjects is a richer, more mature experience than any 
competing weh application development environment. A 
major reason for this superior programming experience can 
be laid at the feet of EOKey ValueCoding, 

EOKeyValueCoding is simultaneously a powerful 
protocol (in Objective C) and interface (in Java). When the 
EOControl framework is imponed, all Objective C classes that 
inherit from NSObject receive EOKeyValueCoding behavior, 
rrhe EOControl framework is imported automatically into 
WebObjects apps and frameworks. You do not have to 
explicitly import It in to your WehObjects app or framework 
project.) In Java, when the developer creates a subclass of 
EOEnterpriseOhject, EOCusUjmObject, EOGenericRecord or 
WOComponent, then EC!)KeyValueCoding is available. 

What is remarkable ahrmt EOKeyValueCoding is luw 
universally powerful it is. With this protocol/interface, the 
WebObjects and EOF frameworks know how to access 
custom instance variables (ivars) from within your .suliclass. 
Using the melliods valueForKeyO and takeValueForKeyO (in 
Objective C valueForKL 7 : and takeValueLforKey:) WOl- and 
EOF can acce.ss your ivars through .standard API. In addition, 
EOKeyValueCoding provides the bridge within EOF for 
effective eniity-rclaiionship mapping. 

In valueForKeyO. this standard method allows a lookup 
of an ivar from both WOF and EOF classes. Consider a 
WOComponent subclass that needs to fill in the value of a 
String object in the dynamic WO.Siring eiement, The 
WOString is bound to laslName f>f an UnterpriseObject (EO) 
which represent the employees of a corporation. 

Okdkk ok Access 

1. The component .subclass searches for a public accessor 
method based on the key name. With a key of “lastName^ 
valueForKeyO kx^ks for a method named gerLastNameO 
or lastNameO. In Objective C, it looks for a method 
named getLastName or -lastName. 

2. If a public accessor method isn't found, the componem 
sui)dass searches for a private acces.sor method based on 
key. Note that traditionally in the Apple frameworks, a 
private method is distinguished by a preceding underbar, 
In this case, valueForKeyO looks for a method named 


_getLastNameO or _lastNameO. In Objective C, it looks for 
a method named _getLastName or -JastName. 

3. If an accessor method isn't found and the class method 
accesslnstanceVariabiesDirectly returns true (in Java) or 
YES (in Objective C), valueForKeyO searches for an ivar 
based on the key name and returns its value directly. For 
the key “lastName”, this would be JastName or lastName. 

4. If neitlier an accessor method or an ivar Ls found, die default 
implemcntati{)n invokes liandleQuer^^WithUnhoundKeyO in Java 
or handleQue^WidilinbtJundKey: in Objective C, The default 
implementation of this method will raise an NSExceptian. 

Sometimes exceptions are raised because although ivars 
have changed or been deleted for some reason the 
componem subclass or ihe frameworks still expect the ivar to 
exist unchanged. In these situations after 10-15 minutes of 
proverbial pounding sand, we would override 
handleQueryWithUnboundKeyO and check to see if the 
disputed ivar is being looked up, and if .so, return nil or null. 

EOKeyValueCoding API to Access Instance Variables 

For another example, suppt^se that you have an EG using 
a BigDecimal or NSDecimalNumber with ""someDecimal” as 
one of its ivars, 

Java 

(BlgDeciinal)iDyEO, '/aliieForKey (''soiriGDetiinal '*); 

EKJtf: you must atways downcitsi your objects when using valueForKeyO iTi Java 

Objective C 

(royKi valueForKey 3@"soiiieDeciinal"l ; 

Mere is the operaiional order for takeValueForKeyO 
(takeValued'orKey: in Objective C) 

1. The EOKeyValueCoding methods search for a public accessor 
method of the form selKey (selKey: in Objective C) 

2. If a public accessor method isn’t found, 
EOKeyValueCoding searches for a private acce.s.sor 
method of the form _setKey (Objective C _setKey:) 
invoking it if such a method exists 


Please feel free to contact the authors with questions or comments on the an ides at webobjectseol@mac.coni. We may not Idc able to reply personally 
to all emails hut every" one will lie read. 
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What are Protocols and Interfaces? 

Objective-C protocols and Java interfaces represent 
essentially the same objeci-orieiited concept: the ability to 
declare methods that are independent of a particular class 
and can be implemented by classes in any heirarchy Any 
Objective-C class that declares itself to conform to a 
particular protocol or Java class that implements a 
particular interlace must, by default, implement the 
methods declared by that protucol/interface. The 
approaches taken are different with the Objective C 
approach being arguably more flexible. 

Confused? Don’t wt>rry — maybe an analogy can make 
things clearer Imagine you Ye writing a nature simulation 
program which requires that various "animals” have a 
swimming behavior Since entirely different kinds of 
animals can share behaviors even if they conic from entirely 
different species, phyla or families, not every swimming 
creature inherits from the same class (whales, trout, dogs 
and humans are all “swimmers” even though they inherit 
from different classes of '"animal”: whales do not inherit 
from trout because wliales are mammals while trout are 
lisli, dogs do not inherii from humans because dogs are 
canines while humans are primates, etc). 

In your swimming simulation, you need to have your 
objects implement a specific type of behavior, but not 
neeessanly the same way You also want to show what 
happens when certain types of animals are not able to swim 
in water (like most species of birds, for example). So, if you 
are writing an Objective C program, you declare a 


'Swimming’ protocol. Correspondingly, if you arc writing a 
Java program, you declare a 'Swimming’ interface. 

The Objective-C protocol declaration may 
look like this: 

' r gti? c 0 1 ■ SwlTn’ri i ng • ' ; - 


' t void J t rea d Wat e r: • 

- (. VO i d w imF tee le; 

V (void)breathe: 


§end 


The Java interface declaration may look like this: 

pub 1 1 c it: t € r f ec e S v^imiri g { 
public void treadWaterU; 
public void sviiiiFreestyief ):; 
public void breathe!f ) f 


hi the swimming simulation, dogs, humans, whales, 
trout and ducks iniplcnicnt the ^Swimming protocol or 
interface method declarations and w^oiild swim in ways 
unique to those species. A hummingbird, on the ocher 
hand, would probably not implement the Swimming 
protocol or interface, and therefore drowm if left in water 
for a prolonged period of time. 


3. If an accessor method isn’t found and the class method 
accesslnstanceVariablcsDircctly returns true or YES, 
takeValuelYnKeyO searches for an ivar based on the 
expected key name and sets the value directly in Java. In 
(])hjec[ive C, the old value is auto re leased and the new 
one is retained. For the key “lastName”, this woukl be 
_lastName or lastNanie, 

4. Tf neither an accestsor method or an ivar is found, die default 
implementation invokes handleTakeValuePorUnboundKey in 
Java and handleTakeValueTorlinlxxindKeyi in Objective C. 

It is important tiiat while this method lias been very well 
debugged, sometimes phantom keys can be looked up long 
after they “died”. It is prudent to override 
handleTakeValueForUnboundKey in this situation to check if 
the phantom key is being looked up and, if so, do nothing. 

To set the ivar someDeciiiiar to a BigDecimal object of 
value ‘1\ you would: 

Java 

myEO.takeValueFoirKey (new BigDecimalT') . ""sotneDecimal) ; 
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Objective C 

[inyEO takeValue: fNSDecimalUumber 

deciTtialN-uinberWithString:®”!"] forXey:@"soin.eDeGimar'] 

What happens when your code accesses ivars that no 
longer exist? 

This is an inieresting situaLion. Most often, this occurs 
when a developer has removed an ivar From his EO without 
deleting all references to it from the code. EOF's default 
behavior is to invoke handieQueryWithlJnboundKey in Java 
and handleQueryWithUnboundKey; in Objective C which 
throws an exception. Devekipers can override this if they 
desire some other behavior or have it fail gracefully (not at 
all recommended but if it is absolutely n^c^ssary ... ). 

Corollaiy behavior occurs w'hen using takeVakieEorKey 
(Objective C takeValuedorKeydon an ivar dial doesn't exist. EOF 
automatically invokes die method handleTakeValueForlJnlKxmclKey 
(Objective C liandlel a!ceValue:lorUnlx>LindKey:). Tliere are metltcxls 
used as private API witliin liOF that are publicly exposed, 
stored Vain eForKey and lakeStoredValueForKey in java 
(stoiedValueForKey: arul lakeStoredValueTorKey; in Objective C) are 
used to access anri/or initialize the receiver’s values as they are 
stored in die database. 

Making Life Easieu 

There are some methods in FOKeyValueCoding that 
make life considerably easier to get things done. And in the 
case of Oiijective C, it provides a very crjnvenient way to 
implenieni ihe NSCoding protucnl within a class. 

Va I LIeForKey Ihi i h (Oh jeelive C v a 1 11eF^f j rKey Ihii h:) alio ws 
you to return the value at the end of a relationship path's 
property. For exaiiiple, if you wanted to find the name of 
anEmployee’s department, you warn Id; 

Java 

(String}atiEmplDyee, valueForKeyPath ("departtnent. name") ; 


Objective C 

lanKmployee valueFarKeyPath :@>''departinent.name”] ; 

The relationship from aoEmployee to its department was 
iraversed and the department’s n;ime accessed. Having done this, 
you can u.se anoilier method takeValuePorKeyPath (Objective C 
fakeValueJbrKeyParh;) to set the name of a relationship’s 
property. 'lb change the name of anEmployee’s department: 

Java 

anEmployee.takeValueForKeyPath{“Data 
Processing''.''department .name”): 


ObjecdveC 

[anEmployee takeValue:@''Data Processing: 
forKeyPath *©"department,name”] : 

valuesForKeys (Objective C valuesForKeys;) returns an 
NS Diet ion ary of the key-value pairs of an object. It’s corollary 


What are IVARS/INSTANCE YARiABLES?.-^-^^* 

Instance variabJes (also known as ivars) are the 
specific variables of data for an object instance. Wbat 
does that mean? 

say you have an Employee class which ii 
geaertGaily defines what an employee looks like,.; An f 
Employee has a first name, a last name, and a Social 
Security number^- In Objective C^ an Employee would 
look like this: 

©interface' Employee : NSObject 

KSStting ’firstNaroe; 

KSStJting •la^tHame; 

KSSfrlng ‘ssn; 

I ■ ■’ 

©end . 

And in Java, an Employee would look like this: 

public. Employee esttends Object I 

protected Strang firstMamn; 
j-protficted String ia^iitKame; 

protected String sari: 

1 

Employee objects, like die employees that represent 
the CEO and the vice-president would have a firstNamc, 
lasiName, and an ssn instance variable. For the CEO, her 
instance variables might look like this: firstName - “Jane", 
lastName = “Smith", ssn = *'555-12-1234". For the vice- 
president, his instance variables may look like this: 
firstName = "John”, lastName = "Browm”, ssn = “555^12- 
9876". For the CEO Employee object, its variables 
contain unique data, and likewise for the vice-president 
Employee object as well. 

EOKeyValucCoding provides a consistent API tor the 
frameworks to access the ivars for the retrieval and 
modification of data. Whenever a firstName is displayed 
on a w^cb page in a WebObjccts app, it is retrieved 
through liOKeyValueCioding’s APIs, The corresponding 
modification of ivars occurs through 
EOKeyValueC^oding’s APIs on all objects. This consistency 
allows developers to create applications and frameworks 
faster because they don’t have to think about how the 
iva rs n e ed to b e a ccessed. 


method takeVa I uesFrom Dictionary (Objective C 

rakek'hliiesFromDictionary:) sets the ivars of an object to the 
values of the NSDictionary pas.sed as an argument. 

These methtxis can used to quickly implement the 
NSCxxling pnXocol in Objective C. The NSCIbdiiig jirotocol Gin lx? 
used to make an t^liject aichivable to disk. It consists of methods 
encodeWithGxlen and initWitliCoder:. Imagining a situation where 
a developer wlslied xu ijuplement an Employee class rlxit didn’t use 
EOF. Some form of persistence needs to be created for die 
Employee objects by implementing die NSCoder protocol. 
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development revolution 


You're port of the movement 


II find two innovative 


technologies oMowing you to deliver the most 


comprehensive software solutions available 


4D and WebSTAR 


Time is short. Seize the moment 


Maximize your efforts using revolutionary 
development tools and Internet Servers that 
deliver now and into the future. 


Don't waste today. 

Download your future. Ignite your potential 
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Implementing persistence 

Employee.h 

/^import <Fotindation/Foundation,h> 
©interface Employee : NSObject <NSCoding> 
I 

NSString •firstNama; 

NSString ‘lastName: 

I^SString *ssn; 

i^SString *streetAddressOne: 

iJSString ^streetAddreseTwo: 

NSString ’city: 

NSString ’state; 

NSString ‘zlpCoda; 

NSDecitnalNumher * sal ary: 


// Skip the accessors. 

// EOKeyValueCoding'based methods 

- (NSDictlonary *}objectAsB±ctionary; 

- [HSArray *JattributeNames; 

// NSCoding methods {which we declare for this example..,) 

- (id)InitWithCoder:[NSCoder *)coder: 

■ (void)encodeWithCoder;CNSCoder ’)coder: 

©end 

Employee .TE 

/import Employee,!'^ 

#import <EOControl/EOKeyValueCcidlng,h> 

©implement ation Emp 1 oye e 

// EOtUyValueCodlng-bascd methods 

- (NSArray *)attribnteKames 

I 

// Return the ivar'keys'in an NSArray 

return [NSArray arrayWithObjects: 

©"f IrstName*', 

©"laatName’*. 

©"ssn"'» 
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©"streetAddressOne”* 

©"streetAddressTwo", 

©"city". 

©"state”, 

©"zlpCode", 

©"salary", 
nil] : 

1 

- (NSDictionary ‘jobjectAsDictionary 

[ 

// Return the object as an NSDictionary using the ‘attribntcNamcs 
// method to define the keys of the object 

return [self valuesForKeys:[self attributeNames]]; 

) 

- [NSString ’)descriptidn 

( 

// Inherited from NSObject 
// Represent the object as an NSDictionarj' 

return [[self objectAsDictionary] description]; 

1 

// NSCoding methods 

- {void!encodeWithCoder:(NSCoder ')coder 
I 

// NSDictionary already conforms to the NSCoding protocol, as 
// well as NSString and NSDecimalNumber 
[super encodEWitbCoder;coder]; 

[coder encodeObject:[self ObjectAsDictionary]]: 

return; 

I 

' [ld)iiiltWithCoder; (NSCoder *)cod€r 

t 

NSDictionary 'newSelf; 

self = [super InityithCodet;coder] ; 
newSelf = [coder decodeObject]; 

// Since we’ve already archived ourselves as an NSDictionary, 

// we can probably take our values from the dceoded NSDictionary 
[seif takeValuesFromDlctlonary:newSelf]: 

return self: 

1 

©end 


This is a Simpler (and faster) way of implementing NSCoder, 
particLiiariy as the number of ivars increasses. In our example, 
the traditional approacli would have required 10-12 additional 
lines of code for dealing with all of tlie ivars individually. Instead 
of all that, the object is archived as an NSUiciionary^ and the 
EOKeyValueCoding protocol takes care of tlic rest. 


Conclusion 

EOKeyValueCcxling provides a coasLstent and convenient API 
to access ^md manipulate aU of your ivars within your objects. It also 
provides a LiniIV)rni way to represent aU objects as NSDictiomries lo 
Wel>0!)jects and EOF Tliis helps make object-oriented programming 
witliin Wel:)01:)jects much simpler wteh is l?eneficial regardless of 
your level of expertise. 

Unsurprisingly, EOKeyValueCoding is too Ltseful to be kept to 
EOF and WebObjects alone. Apple recognized its potential by 
migrating it for Java Client as NSKeyValueCoding. Even more 
signiftcant, NSKeyValueCoding appears to be moving into 
Foundation for use with Cocoa pix>gramming. Otlier than some 
source code ^import changes, aJl die Al^l stays consistent which now 
means that persistence widiin classes w'iJl become much simpler. 
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QUICKDRAW 3D 
TRICKS 


By Tom Djajadiningrat and Maarten Gribnau 


Cubby: Multiscreen Desktop VR Part III 


Reading an input 
sprocket device and 
calibrating Cubby 


Introduction 

fn this month's final <;pisode of 
our 'Cubby: Multiscreen Desktop VR' 
trilogy we explain how you read the 
InputSprocket driver from part H, how 
you use it as input for the cameras 
from part I and how you calibrate the 
input device so that it leads to the 
correct head position. 

Relating the Virtlial Cubby to 
THE Real World 
Before we can talk calibration we 
need to establish how the virtual 
Cubby relates to the real world. We 
have made life easy for ourselves by 
choosing the same orientation for the 
coordinate system of the real Cubby 
as the virtual Cubby. We also made 
the dimensions of the virtual Cubby in 
QuickDraw3D units equal to the 
dimensions of the real world Cubby in 
millimetres. This is determined by the 
constants kHalfEdgeLength and 
kEdgeLength which are half an edge 
length and a whole edge length of 
Cubby respectively. You can find 
these constants in MyDefines.h (Listing 
1), The Cubby we built has an edge 


length of 195mm and so weVe given our virtual Cubby 
an edge length of 195 QuickDraw3D units. In a sense the 
scale of the virtual Cubby is arbitrary. As long as 
everything is scaled equally (the background planes, the 
model, the lights and the camera) you end up with the 
same perspectives. If you like you can create a virtual 
Cubby with an edge length of 1. However, we think that 
the way we do it here has one major advantage: the 
coordinates in QuickDraw 3D units that you see during 
debugging are meaningful because you can directly relate 
them to sizes in millimetres in the real world. For 
example, if you end up with a camera position that is 
20000 QuickDraw 3D units from the origin, you know that 
somediing has gone haywire because 20 metres is well out 
of range of the tracker. 

Listing 1: MyDefines-h 

// the width and half the width of a Cubby edge in QD3D luiits 
^/define kEdgeLength 195 
jfdefine kHalfEdgeLength 195/2.0 

We use these constants for three things: 

1, setting the size of the background planes 

2, scaling the model read from disk to Cubby's display space 

3, setting the area cut out of the view plane 

Setting the size of the background planes 

Listing 2 shows the creation of the background planes. 
Each background plane is a polygon. The constant 
kEdgeLength is used to indicate the vertices of a polygon. 

Listing 2; DisplaySpacc-c _ 

DisplaySpace 

TQ3 Ge ome t r yOb j ec t thePo1y gonZO, th ePoly gonXO, t heP oly g o nY0; 
TQlPolygonData theDsta; 
long i ; 

Ttl3Vertex3D theVerticeeZa [4] “ [ 

0 . 0 . 

kEdgeLength, 0, 0*nil* 


Last month, when Maarten threatened to withdraw his indispensable contribution to this month’s final episode of Cubby, Tom 
hurried to explain to him that the trick in crafting ‘about the author’ notes is to spend at least as much time on it as on the 
article itself. He is disappointed that his suggestion for an article with guidelines for writing ‘about die author’ notes was 
received with little enthusiasm by MacTech's editors. 


December 2000 • MacTech 


Cubby: Multiscreen Desktoi* VK Part III 


27 













-C. 


-XC^S^- 


fs for Programmers! 




REALbasic 2.1 


Code Warrior for Mac OS is a powerful Integrated 
development environment that includes a fully object’ 
oriented application development framework called 
PowerPlant. With Code Warrior for Mac OS you can quickly 
develop reliable, professional quality applications that 
e)(ecute on Classic Mac OS, or OS X, 


MEWYtnion 


REALbasic is the programming tool for "the rest of us." Each 
window type, control, and menu is preconfigured and instantly 
works as it should. The drag and drop Window Editor allows 
you to quickly and easily create your application's interface so 
you can focus on the important part-your creativity. Includes 
900 page manual, examples and tutorial on CD ROM) The 
professional version has all the power of the standard, plus 
database support and allows you to cross compile your code 
for Windows with a single click] 

As low a 


INBWfl 

^^sic I f 


Spotlight is the first Macintosh "Automatic Debugger". It can 
automatically locate run time errors In your code and display 
the offending source code line. Unlike similar tools on ocher 
platforms Spotlight is easy to use. No source code changes 
are necessary for application debugging. Spotlight can 
automatically check for wild pointers, memory leaks, 
overwrites, underwrites. Invalid dereferencing of handles, and 
even toolbox parameter validity checking ■ spotlight knows 
Macintosh verifying parameters to over ^00 toolbox calls. 


Resorcerer 2.2 


’'mi 


Resorcerer is the only supported general-purpose resource editor 
for Macintosh, Relied upon by thousands of Mac developers, 
Resorcerer features a wealth of powerful yet easy-to-use tools for 
easier, faster, and safer editing of Macintosh data files and 
resources, Whether you have to parse a picture, debug a data fork, 
design and try out Balloon Help, create a scripting dictionary, create 
anti-aliased icons, design and edit a custom resource with 40,000 
fields in it, create C source code to run a dialog, or any of hundreds 
of other resource-related tasks, Resorceref's magic will quickly save 
you time and money. 


-4m 

$239 


VOODOO Server is a version control system for software 
developers using Metrowerks CodeWarnor under Mac OS. 
VOODOO Server and the corresponding VOODOO clients [the 
included Code Warrior VCS plug-in and the VOODOO Admin 
application) are designed to offer reliable and robust version 
control features while minimising the administrative overhead 
that usually accompanies version control, IF you’re a single 
programmer or managing a team of developers, version control 
can make or break your project. Do it right, with VOODOO 


Future BASIC 3 


One of the most fiexible and powerful development 
environments on the Macintosh today! Easily create programs 
with the visual program editor, drop into the BASIC editor to 
define powerful logic with the worlds easiest programming 
language, or work directly with the Macintosh toolbox. The 
only BASIC compiler on the market that gives you 100% access 
to all of the power of the Macintosh toolbox! 


4l 


NEWI< 


$159 


and hundreds more/ 



HkLito 


Toolsnu^*" 


Script 

Debugger 

$189 


Page Charmer 2.0 

$139 


Scripter 2.0 

$179 
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Master the Web! 



Mon ptior the bandwidth usage of up to five different machines on your 
network! Do you need to upgrade your Webserver? How hard is your 
eMail server working? Aie you gelling all the bandwidth you're 
paying for? Not only can CyberCauge answer aJI these questions, 
new features allow CyberCauge to eMail or page your network 
device becomes unresponsive r passes a threshold of usage you 
define - an essential first One of defense for early detection of denial 
of service attacks and necesity for warning you and tracking quality 
of ISPs that may have brown outs and shutdowns. 


VWebSTAR Server Suite is a complete set of powerful and easy- 
to-use Internet servers for the Mac OS. Effortlessly serve web 
pages, host email accounts, publish databases, and share files ' 
all with a single application on one Mac! WebSTAR Server Suite 
Is perfect for Internet or Intranet serving, single or multiple 
sites, sitialll and large businesses ■ it’s power and ease-of use 
saves any organization time and money. 


NEWR 


Funnel Web is the ultimate web analysis solution for 
professionals. Specifically designed for profiling web Site usage 
and monitoring customer usage patterns, Funnei Web is ideal for 
examining server performance and online effectiveness. Funnel 
V\feb can anal)^ log file formats fiom any server, \AfebSTAR, 
Wbbfen, even Unix or NT hosted ervers. Discover the most 
popular pages on your site, track server loads 6t optimize server 
performance, prarie visitors based on organization, domain 
name, country, browser, etc. Funnei Wbb does it all! 


NetBarrier offers a Personal Rrewall, Antivandal pnotecbon. and 
1 nternet Fi Etering. Protect your machi ne from 1 ntru sions by I nternet 
or AppleTalk, Incorrect passwords and individual actions are 
logged, you are alerted to hostile actions, and intruders are easily 
isolated, internet Filtering allows you to he sure that passwords, 
credit card numbers., and other sensitive information can never be 
exported from your computer - the content itself is filtered before 
any transfer! [Rated 4 mice by Macworld Magazine] 


Funnel Web Pro 


NetBarrier 


...and great hardware solutions! 


2 USB PCI Card , Dr. Bott Moni S witch adb dr U SB 


Add two USB ports to your older Macintosh. Connect up to i 

127 devices to the Universal Serial Bus [USB) that is 

Apple's new standard for desktop connectivity. USB mouse 
devices, keyboards, joysticks, game controllers, printers, wE 

; scanners — connect them all to your current computer. 

Installs in minutesl , 

$ 32 ® 

Do you need 4 monitof^ and 4 keyboards for your 4 servers? S 

With Dr Bott Moni-Switch you can connect a single keyboard i iS 

and monitor to up to ^ machines at once! A simple flick of a { g 

switch directs the vkieo input and keyboard commands to the 1 | 

appropriate CPU! Available In USB and ADB models, with 2 ; 

or 4 machine support, and bundles with USB PCI cards so V 

you can mix and match USB and ADB machines with the 

same Moni-Switchf Great for programmer to do back > ' 

ground compiles, ideal for server rooms overcrowded with 
monitors and keyboards! 

Macsense USB Full Size Keyboard 

Macsetisig Internet ShiiHng Router 

Just plug this keyboard into your Mac and start typing! The mSi 

UKB-GOO keyboard from Macsense is designed to get you 

' worries. It features two tone translucent design, colored to 

: match your favorite flavor of Macintosh. It offers soft touch . 

with positive tactile feedback and build built in USB port on M M 95 

either side of the keyboard. Includes a 5' USB cable and is 

100% Macintosh compatible, simply plug and play, as easy ~ 

as Macintosh! 

Looking to get your whole office online without shelling out ^ 

^ thousands of dollars? If so. the XRouter Internet Sharing K 

Hub offers the [perfect solution, This amazing Ethernet-to™ 

Ethernet hub connects an entire network of up to 252 users 
to the Internet using only one ISP account and one Cable or 

DSL modem) . . ^ _ 

$199 






















































kEd £€ Length > kEd geLe ngth * 0,ni1» 

0, kEdgeLangth» 0. nilI; 

TQ3Vertex3DtheVerticesX0[4l = I 

0,0, kEdgeLength, nil, 

0*0. 0. nil. 

0*kEdgeLength. 0. nil* 

0*kEdgeLength, kEdgeLength, nlll: 

TQ3Vertex3D theVerticesYO [4] = f 

0* G, kEdgeLength* nil, 

k£d geLen gth, 0. kEd geLength * nil, 

kEdgeLength, 0.0, nil, 

0. 0*0* nill: 

// create new polygon objects. 

U four comm per polygon. 
theData. nimiVertices = 4: 

// p()int to our array of yerticcs 
// for the polygon in the Z=(l plane. 
theData*vertices = theVerticesZO: 

// polygon itscif has no attributes. 
theData.pDlygoiiAttributeSet ^ nil: 

// create the polj'gon. 

theEnlyganZD “ Q3EalygC5n_NewC^theData); 

// point to our array of vertices 
// for the polygon in the X=0 plane. 
theData.vertices = theVerticeaXO; 


box' minimum and maximum comers. We also calculate 
theBBoxDiagonal, the length of the diagonal of the 
bounding box. We then calculate theDisplaySpaceDiagonal, 
the length of the diagonal of Cubby’s display space. The 
ratio of these two lengths gives us the scale factor for the 
model so that its bounding box fits within Cubby’s display 
space. Note how we have a fiddle factor kScaleRnelune. 
This factor makes sure that the model ends up slightly 
smaller than Cubby’s display space as it does not look very 
good when the model touches the background planes. We 
chose kScaleFineTune = 0.75 though you can of course 
change it should you prefer a tighter or looser fit. We can 
now w^ork out the required transformation matrices. The 
first one, theTransMatrix! , translates the centre of the model 
to the origin. The second one, theScaleMatrix, scales the 
model around the origin. The third matrix, theTransMatrix2, 
translates the model to the centre of the display space. 
Finally, we concatenate these three matrices in the order 
that they were created. The resulting matrix in the 
fModelMatrlx field of gDoc is submitted for rendering in 
SubmitOneView of the source file Rendering.c. 


// create the polygon. 

thePolygonXO “ Q3Polygon_New(&th&Data): 

// point to our array of veniccs 
// tor the polygon in the Y=0 planL-. 
theData.vertices “ theVerticesYO; 

// create the polygon. 

thePolygonYO “ Cl3PQlygon_Nevi{&theData): 


Scaling the model 

We want to scale and translate the model that was 
read from disk so that it fits within and is centred within 
Cubby's display space. This is accomplished through the 
procedure ScaleModelToDisplaySpace wathin the source file 
ReadModelAndScale!t.c (Listing 3), U should look pretty 
familiar to you as similar procedures are found in most 
examples from the QuickDraw 3D SDK, Basically, what 
we do here is calculate the bounding box of the model 
and use the dimensions of the bounding box to scale and 
translate the model so that it fits and is centred within 
Cubby’s display space. Let’s look at the code in detail* 

The first thing we do is call GetModelBoundingBox after 
which theViewBBox holds the bounding box. From the 
bounding box we can work out its dimensions along the 
three world axes. The next thing is a check to see whether 
ail these dimensions are smaller or equal than kQ3RealZero. 
This could happen if the file read from disk was a single 
point. We want to avoid a bc:)unding box of which all three 
dimensions are smaller than zero as that wxmld give 
scaling problems later. So if it happens we set the 
dimensions of the bounding box to a very small number 
(0,0001), We work out the bounding box’ centre 
theBBoxCenter by calling Q3Point3D_AfffneConnb with the 


Usting 3: ReadModelAndScalelLc ___ 

Scale M odelToDisplaySpacc 

void ScaleKodelToDisplaySpace(DocumentPtr inDoc) 

I 

^define kScaleFineTutie 0*75 


TQ3BoundinaBox theViewBBox; 

float theXSize, theTSlze, theZSize; 


float 

TOPointiD 

TQ3pQint3D 

TQ3Vectar3D 

float 

float 


theWeightsU] = I 0*5. 0*5 1: 
thePoints[2|: 
theBBoxCenter: 
theDlagpnalVactor: 
theBBoxDiagonal: 

theDiaplaySpaceDiagonal; 


float 


theScale^ 


TQ3Matrix4x4 theTransMatrlxl, 

theTranaMatrix2, 
theScaleMatrix: 


// Get the bounding bus of the model. 

GetModelBoundingBox(inDoc. fiitbeVlevEBox): 

// Work out the dimensions along the axes. 
theXSiae = theViewBBox,iiiax*x - theVlevBBox*miii*x: 
theYSize = thEV±ewBBoK.iiLsx*y ■ theVievBBox*mii*y: 
theZSize = the¥iewBBDX.tELax*z ' theVieirfBBox*min*Ei 

// If we have a point mcHlcI, then the'UieViewBBiix' 

// would end up being a singularity' at the location 
// of the point. As this bounding 'box'is used in 
// scaling the model, this could give problems, 
if (tbeXSize <= kQ3ReaiZerQ Lh 
theYSlze <= kQ3RealZero 
theZSize <= kQSRealZero) 

( 

// Set the comers of the bounding box to a v ery small number. 
thGViewBBox*aiax*x 0.0001: 
theVievBBox*Jiiax*y 0.0001: 
t heViewBB Qx * max * z += 0 * 0001: 

theVlewBBox*niin*x -= 0*0001; 
tbe?levBBox*min*y 0*0001; 
theViewBBox.min.z = 0.0001: 

1 


30 


Cubby: Multiscreen Desktop VR Part [II 


MAdTECH • December 2000 






//Work out ilic cenirt ijf the bounding box. 
thePoifits [0] ^ th^ViewBBox.tiiin: 
thePoints[l] ^ theViewBBox.max; 

Q3Poliit3E_AffineCDiiib [ thePoints, theWelghts, 

2* &thsBBoxCenter); 

// tlie length of the diagonal of the bounding Ixjx. 

Q3Point3D^SuBtract( fiitheViewBBox.max. 

&theViewBBox*rain, 
StheDiagonalVector); 

theBBoxDiagonal^ Q3Vector3D_Length[&theDiagonalVector): 

// the length of the diagonal of the display spate. 

theDisplaySpaceDiagonal = sqtt(3 * pow(kEdgeLength.2)): 

//'Phe .stale to make the mtjdtl fit within the spate. 

// kSealeFinelunt = 1 gives a tight fit,The smaller you 
// make it, the smaller the model ends up 
// within the display spate. 

theScalE ^ kScaleFineTune * ( theDisplaySpaceDiagonal/ 

thGflBoxDiagnnal )t 

// First, we set up a matrix for iransbtjng 
// the centre of the model to the origin. 

Q3Hatrlx4x4_SetTrannlatG ( ^theTransKatrixl. 
-theBBoxCenter*x. 

‘theBBoxCentEi.y, 

-theBBoxCenter*zj: 

// Second we set up a matrix ftjr scaling 
// the model to fit Cubby's space. 

Q3Matrix4x4_SetScale ( itheScaleMatrix, 
theScale* 
theScale* 
theScale); 

//Third, we set up a matrix for translating the model 
// to the middle of Cubby's dispjay space. 

Q3Ms.trix4x4_SetTrflnslate [ ^theTranGMatrixZ, 
kEdgeLength/2,0, 
kEdgeLength/2.0, 
kEdgGLength/2.0); 

// Finally, concatenate die matrices. 

Q3Mat rix4x4_Multiply[ ^thaTransHatrixl< 
fiitheScaleMatrix. 

S;lnDoG->fModelMatrix) i 

Q3Hatrix4x4_Multiply{ fidnDoc->fModeiMarrlx* 
6itheTranBHat3rix2> 

&itiDoc->fHndelHatrix) j 


Setting the view plane area 

We need to indicate the size of the area that each 
view plane camera cuts out of its view' plane. We need to 
do this only once during initialization of each camera 
since the size of this area does not change during 
execution of our application. The size of the area that is 
cut out of the view plane is determined by the camera 
parameters halfWidthAtViewPlane and halfHeightAtViewPlane. 
Since the area we wish to cut out is square and since a 
background polygon completely fills it, these camera 
parameters both equal kHalfEdgeLength (Listing 4), 


Listin g 4; V ic wCreatio n.c _ _ 

ne w V ie wPlaocCaincm 

// The iispeci ratio of these parameters should equal 
// that of die paneWidth and paneHdght. 

// In Cubby's ciise the screens are squiiie so the aspect ratio = 1. 
thePerspectiveData.halfWldthAtViewPlane = kHalfEdgeLength: 
thePerspectlveData.halfHeightAtViewPlane = kHalfEdgeLength: 


Now that w^e know how the virtual Cubby relates to 
the real world, we can turn our attention to calibration. 

Calibration Procedure 

Why calibrate? 

To ascertain that we correctly measure the head- 
position of the user w e need to ealil>raie the head-tracker. 
Calibration would not be necessary' if we could place the 
origin of the base-unit of the tracker at the origin of 
Cubby and the sensor in the middle of the user's eye. 
Since neither is possible we need to take the offsets in 
position into account. Also, since we wish to mount the 
Dynasight base unit above the display space under an 
angle to provide the best coverage of the user’s work 
space^ we need to take this rotation into account. What 
we are looking for is the matrix w4iich transforms the 
InputSprocket coordinates that w'e get from the tracker to 
the QuickDraw 3D world coordinate system. So how do 
we work out this transformation matrix? 

Conversion from InputSprocket units to 
millimetres 

The numbers that we read from our Dynasight 
InputSprocket driver into our application are not in 
millimetres. The driver works with a coordinate usystem in 
which the axes run from the minimum number 
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klSpAxisMinimum to the maximum number 
klSpAxisMaximum. A look in InputSprocket.h cells us: 

tfdefine klSpAxlsMijiljirum DxOOOOOODOU 
//define klSpAxlsMaxlMM OxFFFFFFFFU 

Unlike most game applications, we are not interested 
in relative movements hut in absolute positions. In order 
to calculate what the coordinates from the InputSprocket 
driver correspond to in the real world we need to agree 
upon the conversion factor. What we have done is to set 
klSpAxisMaximunn to 10 metres. Though in a sense our 
choice is arbitrary we would like to think this is an 
informed choice for two reasons. First, it is well above the 
maximum range of the Dynasight {6m) even with the 
largest possible reflective target (75 mm diameter). 
Second, it gives us plenty of resolution. klSpAxisMaximum 
/ 10 metres = 4,294,967,295 / 10,000 millimetres = 
429496.7295 steps/mm. Tracking technology would have 
to improve pretty dramatically for us to run out of 
resolution. 

So if: 

4.294,967,295 InputSprocket units ” 10 metres 
then 

1 InputSprocket unit = 10,000 nim/4,294,9e7,295 = 
2,3283O64370S0797e-6 mm 

This is our multiplication factor io convert from InputSpiockel 
units L{j millimetres. 

W€>rking out the transfcirmation matrix 

The first thing we do is to convert the Dynasight 
InputSprocket coordinates to millimetres. For this we 
create a matrix rheScaleMatrix. 

We then need to express the Cubby coordinate 
sy.stem in Dynasight InputSprocket coordinates. The 
easiest way would be to measure points on Cubby’s main 
axes, but since these are out of sight of the Dynasight we 
have to use points on the top edges of Cubby’s screens. 
We use the points P, Px and Pz (Figure 1). In the real- 
world coordinate system in millimetres F=I0, dy, 01, 
Px-|195, dy, 0) and Pz-{0, dy, 1951, where dy is the 
distance in millimetres above Cubby’s ground plane. In 
our case dy Ls 2()4mm, tliough your setup will of course 
be different. Though we are working on integrating a 
perky animated paper clip within the Cubby application 
wrhich will talk you through te calibration procedure, for 
the moment we take the following approach. We place 
the sensor consecutively at P, Px and Pz, measure the 
Dynasight InputSprocket coordinates of these points by 
means of our separate little app DynasightReader and jot 
down the readings. We then fill in these coordinates 
where the variables P, Px and Pz are initialized in 
CaJi brat ion Matrix (Listing 5). For a real app you would of 
course have to diink of a more elegant way to capture the 


Dynasight InputSprocket coordinates. 



Figure L 'fbe points io imrk out the cafthration matrix. 


Using these three points we then calculate the vectors 
PPx and PPz and normalize them into Xnornn and Znorm 
re.spectively. Using the cross-prr)duci of these vectors, we 
calculate a unit vector Ynorm w-hich is perpendicular to 
both Xnorm and Znorm. Now we have an orthonormal base 
formed by the unit vectors Xnorm, Ynorm and Znorm which 
specifies the orientation of Cubby. The rotation matrix to 
rotate from orientation of the Dynasight InputSprocket 
coordinate system into the orientation of the Cubby 
coordinate system can be constructed by taking these unit 
vectors and using them as the columns of the rotation 
matrix. To save some typing w'e first set the rotation 
matrix to a 4x4 identity matrix and ilien substitute the top 
left 3x3 matrix with die orthonormal base. 

Now work out the vector PO from P to the origin of 
Cubby expressed in the Dynasight InputSprocket 
coordinate system by multiplying the unit vector in the y- 
direclion Ynorm by the distance from P to the origin in 
Dynasight coordinates. By adding the vector PO to point 
P w^e find the origin expressed in the Dynasight 
InputSprocket coordinate system. This is of course a very 
informative point but we could not measure it directly 
since there is no direct line of sight to the Dynasight, 
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What we are ultimately looking for is a calibration 
matrix which when applied to the origin measured in raw 
Dynasight units gives us 10,0,01. So what we do is to rotate 
the origin using the rotation matrix theRotMatrix we just 
created and then use the resulting point temp to create a 
translation matrix theTransMatrix which translates the point 
temp to the origin of the Dynasight coordinate system. 

Finally, we concatenate the three matrices. First we 
scale, then we rotate, and finally we translate. The 
resulting matrix theCalMatrix is returned, 


a and use the resulting point to create the translation matrix, 
QSMat t ix4x4_S etTr ans iat e (StheT r. an sHat r ix, 

-temp,y, 

-temp.z): 

// Concatenate the three matrices; 

// first we rotate, then wc tianslate. 

Q3Mat r ix4x4_Mult i ply ( SttheRotMa t r ix < 

fiitheTransHatrix, 
^thaCalMatrixl: 


return theCalMatrix; 


listing 


TQ3Matrlx4x4 CalibratioiiMat rix(} 
[ 


CalibrationMatrix 


//These coondinaies in millimetres were measured with the DynasightReader app. 
TQ3Point3D P = 1-0.7* 144.6* 218*151; 

TQ3PDint3D Px= f136*2. *94.75* 351.551; 

TQ3pDint3D Pz= {-138.45* -93.45. 343.751: 


TQ3Matrlx4x4 theTransMatrix, theRotMatrix, theCalMatrix; 


//Venical distance from P to ground plane in mm. 

float dy ^ 204: 

TQ3Vector3D PPx. PPz, Xnorm. Ynnon, Znortn, PO; 

TQ3Polnt3D temp* 0; 


// parallel to X, 195mm 

Q3Point30„Subtract(6iPx, 6P, 6PPx) : 

// X normalized 

Q3Vector3D_MonMli2e{&PPx. &Xnonfl) ; 

// paialld to 2 , 1 95 mm 

Q3Point3D_Subtractt4P2. &P, 6PPz) : 

// 2 normalized 

Q3Vectar3D_NoriiiaIize{&PP2. ^Znorci) ; 

//Y normaiizeU 

Q3Vecior3D_Cross(&ZnijrrTi, &Xmjrm, &Ynorm> ; 


// Start with setting the rotation matrix to Identity 
// so that we do not have to lill in all 16 fields. 
dsMat rix4x4_Se 11dent11y(&t heRo tKat rix) : 

//The coluimis of the rotation matrix become 
if the vectors of the orthonormal base of the Cubby 
// etMirtlinate system in the Dynasight e<H)rdinate system, 
theKotHatrix. value[0] [0] “ Xnorni.x: 
theRotMatrix.value[Oj (1] = Ynomi.x; 
theRotMatrix.value[Oj [2] = Znorm.x; 
theRotMatrix,value[l][O] ” Xnonn.y; 
theRotMatrix.value[Ij [1] = Ynonn.y; 
theRotMatrix.value[ll[2] = Znorm.y: 
theRotMatrix.value[2j[0] * Xnorm.z; 
theRotMatrix.value[2][l] = Ynonn.z: 
theRotMatrix.valuel2][2] = Znonn^z; 


//Work out the vector PO (from P to the origin of Cubby) 
// expressed In the Dynasight CfWrdinate system, 

// For tills you need the distance dy fmm P to the 
// origin of Cubby in mnL 
Q3Vector3D„Scale{S!Ynorm,* -dy* &P0) ; 

// Now we can wotk out the origin of Cubby 
// expressed in the Dynasight coordinate system. 
Q3Point3D_Vector3D_AddUP, 6P0.' &0); 


Integration of InputSprocket Code with Cubby 
In the previous episode (Gribnau and Djajadiningrai, 
2000), we introduced the basics of communication 
between InputSprocket applicatiQns and drivers. Now, we 
wil! show how" Cubby configiire.s and reads data from 
InputSprocket drivers. For Cubby, it doesn’t matter if the 
data comes from our Dynasight driver or from any other 
InputSprocket driver. 

Initializing InputSprocket 

Cubby, like any other InputSprocket application, 
needs to initialize InputSprocket before. Listing 6 shows 
ilie ISpJnItialize routine that does the initialization within 
the Cubby application. First of all, InputSprocket is 
loaded with a call to ISpStartup. Tlien, Cubby asks 
InputSprocket to create new virtual elements based on 
its input needs with the ISpElement_NewVirlualFromNeeds 
calk As shown in our previous episode, InputSprocket 
defines every input device in terms of its elements (e.g. 
buttons, axes, directional pad.s, eteJ. An application can 
ask InputSprocket to create new elements based on its 
need.s. With the needs and the elements, Cubby can call 
ISpInit, In response, InputSprocket will initialize the 
drivers and the drivers will auto-configure to Cubby’s 
need.s. Tills means that the drivers w'ill try to find an 
optimal match between the needs of Cubby and the 
elements that they have. 

Listing 6: ISpCubby-c _ 

ISp_lnitjaIizc: 

OSStatus ISp_Initialize( 

DSType creator) 

t 

OSStatus err; 

err ISpStartnpO : 
if (err) t 
retiirii err; 

I 

// Setup the input spnickct elements 
err ” I3pElenient_NevVirtualFroiiiNeeds ( 
kNeed_NeedCount * 
gNeeds* gInputElements* 0); 
if (err) 1 
return err; 

I 


// Rfjtaie the origin into the Cubby coordinate system... 
(23Poirit3D_Tr3nEform(&0. ^theRotMatrix, fiitcmp); 


// Initialize InputSprticket and give it our needs 
err = ISpIniti 

kNeed_fleedCount, // number of needs 
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gNeeds, // amy of needs 

gin put Elements, // array of references to vlrtuaLs 

c r eat or* // creator code 

■ 0 015 \ // suixreatof code 

0, // flags (should lie 0) 

kReEourceID_setl» // a set list resource 

0); // rcserv^ed 

if (ert) \ 
return err; 

] 


// Wc leave keyboard and mouse disabled for ISp 
return noErr; 


Listing 7 shows the needs of Cubby. Actually, it is an 
array of three structures of type ISpNeed. There are three 
needs since Cubby needs to know the position of the 
head of the user in three dimensions. Therefore, the need 
array has a need entry for every coordinate of the head 
position. Each need structure field is filled with 
appropriate values. The need for the x coordinate for 
instance, sets the name field to “Head X”. Another 
important field is the icon field. This is set to the resource 
id of the icon that we want to be shown in the 
configuration dialog box. Furthermore, the element type 
(kiSpElementKind_Axis) and the element label 
(klSpElementLabeLAxia_XAxis) are set. 


Listing 8: ISpCubby.c .. 

ISp_Sho wC o ufigiireD iaiog 

OS S t atus IS p_Sh owGon figu r eDialo g[vold 3 
( 

return ISpConfigure{nil}; 

] 


.Movement 

Is [I] 

13 

; XA)t\S YAKij 

ZAXiS 


Sets: fpefaiift a] [ ancer 1 


Figure 2 The configumHon dialog box 
mlh the Dynasight selected. 


Listing 7; ISpCubby.c___ 

Cubby's need array 

static ISpNeed gNeeda [3tNeed_NeedCount] * 
i 

f "\pHead X". kResourcGlD_needIconBase+kNeed_HeadX. Q* 

0, kISpElG£nGiitKind_Axis. kl SpElei!ientLabel_Axis_XA3?is. 

0. 0, 0 1 , 

{ ”\pRead Y”* kResourceID_needIcof]Base+kHeed_HGadY. Q* 

0. kISpEleraGntKind_Axis. kISpElementLabel„Axi&_YAxis> 

0 . 0 . 0 , 0 1 . 

I “\pHead Z**. kResour{:eID_needIconBase+kNeed_HGadZ, 0. 

D. kISpEleTOentKind_Axis. krSpElenientLabel_AKis_ZAxis. 
0 , 0 , 0 , 01 . 
h 


Configuration 

The drivers might do a good job during auto- 
configuration. However, the major advantage of 
inpuiSprocket is that it allows users to reconfigure the 
mapping of application needs to driver elements. Listing 8 
shows that one call suffices to start the configuration 
process. The ISpConfigure call brings the configuration 
dialog box on the screen if the Dynasight device (or any 
other device with an In put Sprocket driver) is hooked up 
(Figure 2). Internally, InputSprocket starts the 
configuration process and negotiates with the driver as was 
explained in last month’s episode. Cubby is not involved in 
this process which is nice because it does not have lo 
know which device element is delivering data for each 
coordinate. The pulLdown menus in the configuration 
dialog box allow users to select the elements that need to 
be mapped to a coordinate. If no InputSprocket device is 
available, InputSprocket will notify the user with a different 
dialog box (shown in Figure 3). 
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o You nave no devices to configure! 




figure i, Tlje dialog box shoum if there 
are no InputSprockei deinces. 


Reading data from InputSprocket drivers 

After inituilization and configuration, Cubby can start 
to read dam from the elements. Listing 9 shows how Cubby 
reads the x-coordinate of ilie head position. Reading the 
other coordinates follows the .same procedure. First we 
check whether there are event.s waiting for the axis 
element with a call to ISpElement_GetNextEvent, In other 
words: we check whether the x-coordinate has changed 
since the last time this routine was called. If there was no 
error and an event was found, the raw axis value in 
InputSprocket coordinates is exiracted with the 
ISpE1ement_GetSimpleState call. As was mentioned above, 
the raw coordinate needs to be converted to millimeters to 
he useful In Cubby. This is done by calling 
ISp^AxisToCubbyAxis. Finally, the eventH for ilie axis elemeni 
are flushed and the new etjordinate is stored. 


Listing 9: ISpCubbyx 

void ISp_GetHeadX{ISpCubbyState ‘cubbyStatel 


[Sp_GetHe:u1X 


OSStatus 

ISpElem^ntEvent 

Boolean 

ISpAxisData 

float 


error = noErr; 
event: 

waaEvenr; 
axlsValue; 

xValuE ^ ciibbyState'hheadX: 


//Wl- clictk lire axis, Ui hx’ il U was movriJ, if S4j, wc use thut vulut 
error ■ lSpElGmEnt_GetNeKtEvEnt( 

glnputEiementa[kNeed.HeadX]* sixeof(event), 
ve n t, &wa s Eve nt): 
if (1 error wasEvent) 1 

error ^ ISpE1ement_GetSimplestate( 

aInputElenientsIkNeed„HeadX], fitaxisValue); 
if (!error) I 

xValue ' lSp_AxlsToCubbyAxis(axisValue); 

I 

ISpEleaent_Fliish(glnputElements[kNeed_HeadX]): 


cubbyState'>headX = xValue: 

1 


Listing 10 shows the conversion from raw cotjrdinates 
to coordinate.^ in millimeters. The raw^ coordinates are 
assumed to he in the format described above where 
klSpAxisMaximum equals 10 meters. Our iSp_AxisToCubbyAxis 
routine converts them to millimeters in three steps. First 
they are scaled to a value lieTOeen 0 and 1. Then a mid¬ 
point in introduced. The InputSprocket coordinates are 


positive only but axis values usually have a positive as w'ell 
as negative values. Therefore, coordinates are transformed 
to fit lietween -1 and 1, Finally, a multipUcation by 10.000 
will give us the desired millimeters (assuming the driver 
follows the same cemvention). Now the coordinates are 
ready to be used to drive Cubby's cameras. 

Listing 1 0; ISpCabby.c _ 

1 Sp_Ax i sToCu bbyAxi s 

float lSp_AxisTQCubhyAxisC 
ISpAxlsData axis) 

I 

float yaltle: 

static float r = klSpAxlsMaKimura - kISpAxisHiniraum: 

value = (axis - klSpAxisMlnintum) / t: yy value between 0 and J 
value *= 2: //value between 0 and 2 

value -= 1; // value Ixriween 1 and 1 

value •= lOODD: 

yy v^luc Ls now between -10000 and lOtKK] 
return value; 

1 


Aj>plying the Calibiuvtion Mj\TRIX 

Now that w'e can read the raw coordinates from the 
Dynasight and have the calibration mairix, all that 
remains is to transform the raw' coordinates into a 
calibrated head-position by applying the calibration 
matrix. This happens in AdjustCameras of 
ViewPlaneCamera.c (Listing 6). Using the QuickDraw 3D 
call Q3Point3D_Transform we apply the calibralion matrix 
fCalMatrix to the head po.sition H in raw coordinates and 
end up with a calibrated liead position C in the Cubby 
coordinate .system. 


Listing 11: VicwPlaneCamcra-c _ 

AdjustCameras 

yy nppl)- the calibration matrix to conven the 
y/ niw ht^ad fHJsiUtJn to a cmera posititin 
yy in w^orld ctHirtllnaies. 

Q3 Point 3D_T rans for IQ ( in. 

iinDoc->fCalMat rix, 

&C): 


Troitbleshuoting 

If things are behaving erratically make sure you have 
checked all the troubleshooting hints in the previous 
episodes. Here is one more possible pitfall. 

If yotive actually got round to hLulding a Cubby setup 
you may Find that lining up the three projections drives you 
completely up the walk Well, it Ls indeed awkward but 
there is one thing which can make it unnecessarily difficult. 
Even though the QuickDraw3D panes may be square 
(228x228 pixels) tliis does not necessarily mean that the 
projected images are square. Somewhere in the chain of 
scan converter and projector you may loose some 
‘squareness'. If the project ions of the panes are not square, 
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you will never be able to make them line up. If this is the 
case, have a look whether your scan converter or projector 
has a control for the aspect ratio of the image. Most scan 
converters and projectors do. If not, you can always change 
the aspect ratio of the QuickDraw 3D panes in the code. 
The easiest thing to do here is to point the projectors at a 
w'all and fiddle with the settings until the resulting aspect 
ratio is exactly 1:1. To lend you a hand with lining up the 
projections, we provide an optional lining up' texture with 
edge markings and centre lines (Figure 4). You can activate 
it in MyDefines.h by setting kCubePtanesTexture to 500. Your 
screen should then look like Figure 5- 


1 1 I I 1 1 

1 1 III 

'» Jjv J V 




Figure 4 Lining lexture wUh edge 
markings and centre lines, 
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Figure 5. The Hning uj} texture activated. 


Conclusion 

In three articles we have covered quite a lot of 
ground. You should by now have a pretty good idea of 
how virtual reality systems liased on multiple head** 
tracked displays such as CAVE and (iuhby work. In the 
process you have learned quite a few^ nifty techniques. 
You have learned how to create and read an 
IfipLitSprocket driver for an input device with three 
degrees of Freedom. You now^ know' how to support 
multiple views and how to mirror images. And if your 
matrix skills were a bit rusty, they should all be nice and 
shiny by now. Once you have a true 3D display such as 
Cubby the possibilities are virtually endless. We hope to 
he back with rncjre information. In the meantime, please 
clieck out the Cubby web pages starting at 
littp://www.io.tudelfl.nl/id-studiolab/cubby/index.hlml. 
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PROGRAMMER'S 

CHALLENGE 


by Bob Boonstra, Westford, MA 


Crutches 

Crutches? What an odd topic for a Programmer's 
Challenge, you oiighr rhink. Let me explain. This month's 
problem was actually suggested by my wife, whose 
connection with the Challenge has until now been limited to 
the patience required to put up with the amount of time 1 
spend Rinning the contest. She recently had the misfortune 
to break her foot, which has, you guessed it, put her on 
crutches for six or so weeks. Being on crutches gives one a 
new perspective on distance, particularly distance between 
points around the house. And while she tries to stay off the 
fool as much as possible, she still has to get from place to 
place, so the broken foot also motivates one to find w^ays to 
minimise distance. Which leads us to this monih's Challenge, 
a practical extension of the well-known Traveling 
Salesperson problem. 

The prototype for the code you should write is: 

typedef long Node: 
typedef lon^ Weight: 

typedef struct Connection f 

Nodenodel; /* a connection exists between nodel ... V 

Node nodeZ; /*... and nade2 */ 

long distance: /* ... sepiinited by tliis distance 7 

I Connection: 

typedef struct Task [ 

Weight weight: /* you need to carry an object with this weight 7 
Node fromNode: /*... from frotoNode .. 7 
Node toKode; /*... to toNode 7 

] Task; 

typedef enira {kPickUpObject^l< kDropOffObject, kMoveTol 
ActionType; 

typedef struct Action I 

ActlonType action, actions comprising the solution V 
long object. /* kPickUpObject or kDropOffObjea this object 7 

Node node f kMoveto this node 7 

] Action: 

long /• actions in solution V Crutches ( 

const Node nodes [] , /* Nodes defining the pmbJem 7 

long nUniNodes. 

const Connection connections [] , Connections between nodes 7 
long numConnectionSi 

const Task objectsToMove [] . /* objects to be moved */ 
long TinmObjects, 

Node startingNode, r start from this node 7 

Weight maxVeightToCarry. maximum weight that you can carry */ 

Action so 1 ut 1 onPath [] /* return vour solution here */ 

): 

Your job is to write code that will perform a set of Tasks 
and minimize the distance traveled in doing so. Each Task 
consists of moving an object of a specified weight from one 


place (Node) to another. You can travel from one Node to 
another only if a Connection exists between the Nodes, and 
moving between a pair of Nodes requires traveling the 
associated distance along that Connection. 

At the Stan of the problem, you are located at the 
startrngNode. You are given the numNodes Nodes describing 
the problem space and the numConnections Connections 
between them. You are also given numObjects objectsToMove, 
each of which needs to be transported from the fromNode to 
the toNode. You can carry more than one object along your 
journey, provided the sum of the weights of the objects being 
carried does not exceed the maxWeightToCarry. The solution is 
described as a sequence of Actions. An Action consists of 
picking up an object (kPickUpObjeGt) from the current Node, 
dropping off an Object at the current Node (kDropOffObjeol), 
or moving to an adjacent Node (kMoveTo) and canyang all 
objects that have been picked up to that Node. You may not 
pick up an object if doing so would cause the 
maxWeightToCarry to be exceeded. The sequence of Actions 
that transpons all of the objectsToMove to the appropriaie 
Nodes should be returned as the solutionPath, and Crutches 
should return the number of Actions in your solution. 

None of the Tasks will be impossible to perform. No 
object will have a weight greater than maxWeightToCarry, so it 
will be possible to carry each object. It will be possible to 
reach each fromNode and each toNode by traversing 
Connections from the startingNode. Connections may not satisfy 
die triangle inequality, that is, it may be the case that a direct 
Connection between two Nodes is not the shortest path 
between them. No other a priori infonnation about the 
Connections, Nodes, or Tasks is available. 

Your solution will be evaluated first on coReemess (as 
always), and then on score. Your score for this Challenge will 
be the total distance traveled to perform the required Tasks, 
plus a 10% penally for each second of execution time 
expended. Lower scores are, of course, belter. 

The Challenge prize will be divided between the overall 
winner and the best scoring entry from a contestant that has 
not won the Challenge recently. If you have wanted to 
compete in the Challenge, but have been discouraged from 
doing so by the quality of the entries from our veteran 
contestants, perhaps this is your chance at some recognition 
and a share of the Challenge prize. 

This will be a native PowerPC Challenge, using the 
Code Warrior Pro 5 environment. Solutions may be coded in 
C, C++, or Pascal. 
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Next month, perhaps well solve the problem of how to 
mottvate a couple of teenage children to perform these Tasks, 
aliowang the broken foot mc>re time to rest and heal. But 
perhaps that would be too difficult, even for Challenge 
readers. (Actually^ the kids are being very helpful with the 
household chores.) 

Three Months Ago Winner 
Congratulations to Claes Wlhlborg (Sweden) for 
submitting the winning entry to the September Busy Beaver 
Challenge. This Challenge required contestants to do two 
things. First, contestants were to produce a >state “Busy 
Beaver" Turing Machine that write.s as large a number of Is 
as possible when given a blank input tape. Second, they had 
to write a general Turing Machine simulator that executes 
this Btisy Beaver as quickly as possible. The problem 
statement provided a reference to a Turing Machine 
demonstrating that BB(5), the maximum number of Is 
produced by any S-staie Busy Beavei; is at least 4098. Alas, 
none of the nine entries in this Challenge broke new^ ground 
in Busy Beaver research by providing a Busy Beaver that 
produced more than 4098 Is, So tit is competition was liased 
on how quickly the Busy Beaver eouki be executecL 

Claes’ solution ts extraordinarily last, five times faster 
than the .secamd place solution, and more than sixty times 
faster than the third-place s(4ution. Upon investigation, wliiie 
somewhat difficult to understand because of sparse 
commentary, Claes' entiy^ is fascinating. To fully understand 
it, 1 inserted some debugging code and w'atched it in 
operation. I ll try to coiiipensaie for ihe terseness of the code 
by providing some addititmal explanation here. 

The first thing Claes does is to call the 
CreateOptimizedTMRules routine to cxnnpile the Turing 
Machine rules into OptimizedTMRules. Two OptimizedTMRules 
are created for each Turing .Machine rule, encoding !K>th the 
rule and the associated binary input syiTiln)!. Bach 
OptimizedTIVlRyle contains a OneBitActfonRoutines action field 
that combines two elements u( the original Turing Machine 
rule: the move direction, and whether the output symf>oI is 
unclianged, 0, or 1. 'Ihese action.s are encoded as follows: 

abaleft, abaRight, abaHalt - leave the input unchanged and 
move left, right, or lialt 

abaLeflSet, abaRightSet, abaHaitSet - write a 1 and move left, 
right, or liall 

abaLeftClear, abaRIghtClear, abaHaltClear ^ wmte a 0 and move 
left, right, or hall 

This optimization allow^s Claes to factor out some logic tests 
during the Turing Machine simulation, and to avoid modifying 
the output tape w hen it doesn't change. 

The runNBitTuringMachine performs the Turing Machine 
simulation. This routine processes the input tape in chunks 
of either 6 bits or 8 bits in size, trying the former fiisq and 
the latter if the former fails. It creates and uses tw^o additional 
data structures, the TapeSegment stmeture that encodes a 
segment of the Turing Machine tape, and the MacroNTMRule 


data structure that further encodes the OptimizedTMRules. The 
TapeSegment data structure takes advantage of the fact that 
repeating sequences can occur on a Turing Machine tape, 
and do occur on Busy Beaver Turing Machines. It contains a 
symbol field, which is a 6- or 8-bit section of the tmTape, an 
exponent that contains a repetition count for that section, 
and left and right pointers to adjacent tape segments. 

The MacroNTMRule is a little more difficult to explain. 
The 256 Turing Machine states that the problem statement 
requires entries to suppon are expanded into 512 
OptimizedTMRules, and further expand into 512*256 
MacroNTMRules. A MacroNTMRule is indexed by 8 bits that 
identify the OptimizedTMRule, plus of the TapeSegment symbol 
value (6 or 8 bits). In effect, the MacroNTMRule expands the 
.symbol set from 1 hit to 6 or 8 bits, and expands the set of 
Turing Machine states accordingly. 

When runNBitTunngMachine executes the Turing Machine, 
it first looks to see if the MacroNTMRule corresponding to the 
current state lias been created. If not, it calls the 
createNbltMacroRule routine to create it. This routine simulates 
the effect of the OptimtzedTMRules on the current input 
symboh determines what newSymbol output is produced, 
counts the number of OptimizedTMRulas executed for this one 
MacroNTMRule, characterizes the nature of the rule into an 
NBitActionRoutines action, and siore.s a pointer to the new' 
MacroNTMRule state. 

'fhe NBitActionRoutines field charaLterizes tlie MacroNTMRule 
by encoding the move direction, whether llie output is different 
from the input, and wliether the state is clianged after 
processing this chunk of input. The most interesting values for 
ill is NBitActionRoutines held are as Idllow s: 

• tbaBouneeLeft. tbaBounceRight — leave the input unchanged 
and reverse direction left or riglit 

• tTlxiBounceleftChange, tbaBounceRightChange - write 
changed ouipui and reverse direction left or right 

• tTbaTliruIxTl, ibaTliruRight - leave the input unchanged, 
continue moving left or right, and modify the state 

• I'lba'IlirulxjftChange, tbaThruRigh[Change - write changed 
output, continue moving left or right, and modify the state 

• tTIxiThruOpiimized tbaThruRightOptimized - leave die input 
unchanged, continue moving left or right, and stay in the 
same stale 

• tTbaThmClhangcOptimized tbaThruRightChangeOplimized - 
write changed output, continue moving left or right, and stay 
in the same .state 


40 


RROCpKAM.MER’.S Ctl^UiJiNGE 


MacTech • December 2000 





The optimizations in the runNBitTunngMachine code allow 
the final output of Claes' Busy Beaver to be represented in a 
few TapeSegments: 


Segment 

Symbol 

(Hex) 

i^ponent 

(Hex) 


0 

■ 0 ' 

IHO 


1 

1 

i 


2 

36 

1023 


3 

37 

1 


4 

0 

395 




When funNBitTuringMachine returns, it indicates whether 
the attempt to execute with 6‘bit tape segments succeeded or 
failed. If it failed, it is run again using 8-bit segments. While 
the 6-bit optimization is clearly intended to speed up the 5- 
state Busy Beaver Turing machines, it also kicks in for other 
machines. More importantly, the program meets the 
requirement of correctly simulating any 7'uring Machine wdth 
up to 256 states, waihoui hard-coding any particulars of the 
Busy Beaver problem* 

Before RunTuring Machine returns, it copies the 
TapeSegments back to the Turing Machine tape. (Until this 
point, the output of the Turing Maciiine exists only in the 
TapeSegment databaseJ For the 6-bit tape segment case, Claes 
uses an unrolled loop. For the 8-bit case, he uses memset. In 
both cases, the exponent field in the TapeSegment controls the 
number of times a TapeSegment symbol is copied. 

rd encourage you to take a look at Claes solution, I 
found it to he very clever. 

The table below lists, for each of the solutions 
submitted, the number of Is generated by the entry^'s Busy 
Beaver Turing Machine, the number of rules executed by that 
machine, the execution time of the Busy Beaver in 
milliseconds, and cumulative test case execution time. It also 
provides the code size, data size, and programming language 
used for each entry . As usual, the number in parentheses 
after the entrant's name is the total number of Challenge 
points earned in all Challenges prior to this one. 


Name # of Is 

# of Rules 

BB Time 

Time 

Code 


Lang 




(msecs) (msecs) 

Size 

Size 


Ctaes WtWlx>rfi (9) 

4098 

11798826 

0.93 

3.04 

6680 

1(S^0033 

C 

tiust Munter (651) 

4098 

11798826 

5.10 

22.82 

4764 

749 


Mike Miller 

4098 

11798826 

61.49 

.106.9} 

2044 

410 

c 

Rob (51) 

4098 

11798826 

64.92 

311A9 

1432 

716 

C++ 

R^indy Boring 033) 

4098 

11798826 

213.09 

1066.58 

4456 

94 

C++ 

WiUeki! Rit^ken C112J 

4098 

Ti798826 

489.74 

m>M 

912" 

16 

c 

Tom Saxton (165) 

4^ 

'^11^26 

734.27 

3678.8} 

708 

180 

C++ 

Yung-Luenj' Lan 

4098 

11798826 

743.58 

3726,49 

1372 

28 

^ c 

Ladistav Hata (7) 

4098 

47176870 

29M.95 

5922.87 

1520 

750 

c^ 


Decfmbi-r 2000 • lVl4drECH 


A New Breed of 
AppUciithn 
Service 









ft 






' 


wwi^ ihinkDog.com 

r The Premier WebObiects 
I ASP 

















































Top Contestants 

Listed here are the Top Contestants For the Programmer's 
Challenge, including everyone who has accumulated 20 or more 
points during the past two years. The numbers below include 
points awarded over the 24 most recent contests, including 
points earned by this month's entrants, 


Rank Name 

Points 

Rank 

Name Points 

1, 

Munter, Ernst 

231 

6. 

Shearer, Rob 

48 

2. 

Saxton, Tom 

106 

7. 

Taylor, Jonathan 

36 

3. 

Maurer, Sebastiari 

1 68 

8, 

Wihlborg, Claes 

29 

4. 

Rieken, Willeke 

65 

9. 

Brown, Pat 

20 

5. 

Boring, Randy 

52 





BusylkavcrS 

ulong /* ttixm number of rules V BusyBeaverS ( 

TMRule theTMRules[] 

/• preallocated storage, return the rules for your BB machine V 

[ 

TMRule tmOlU = { 

10.0. 1,1.kHoveRightl, 

10.1, 0.1. ItMoveRlghtJ . 

11.0 . 2a.kMoveLeft] . 

11.1. 1 * 1.kMoveLeft]. 

12,0, 0,I.kMoveRight]. 

(2.1. S.KkMoveLeft}, 

(3,0* 0.1.kMoveRightl, 

13.1» 4,1 .kMoyeLeftK 
(4.0* l.KkHalt] . 

14,1* 2.0.kMoveLeftl 


metncpy t th&THRules, tmOl. I0*£flzeo£CTMUule) J: 
return 5’'2: 


AND THE Top Contestants Looiong for a Recent Win 

In order to give some recognition to other participants in 
the Challenge, we also list the high scores for contestants 
who have accumulated points without taking first place in a 
Challenge during the past two years. Listed here are all of 
those contestants who have accumulated 6 or more points 
during the past two years. 


Rank Name 

Points 

Itank 

Name Points 

10* 

Downs, Andrew^ 

12 

17, 

Hala, Ladislav 7 

11, 

Jones, Dennis 

12 

18. 

Miller, Mike 7 

12* 

Day, Mark 

10 

19. 

Nicolle, Ludovic 7 

13. 

Duga, Brady 

10 

20, 

Schotsman* Jan 7 

14. 

Fazekas, Mikios 

10 

21. 

Widyatama, Yudhi 7 

15. 

Selengut, Jared 

10 

22. 

Heithcock* JG 6 

16. 

Strout, Joe 

10 




Tliere are three ways to earn points: (1) scoring in the top 
5 of any Challenge, (2) being the first person to find a bug in a 
published winning sokition or, (3) being tlie hist person to 
suggest a Challenge that I use. The points you can win are; 


typedef Enuin [obaNotyetRefiriEd» 

obaLeft. obaLeftSet, obaLeftClear. 
obaHalt, obaHaltSet. obaHaltClear. 
obaRigbt, obaRightSat* obaRightClear 1 
OneBitActionRoutines: 


TYPES 


typedef struct OptimizedTMRule f 
OneBitActionRoirtines action; 

Btruct OptimizedTMRule ‘newState; 

/* SCI cumcm slate to newState when this rule fires 7 
1 OptiiniKedTMRule: 

typedef enmn I tbaNotYetDefined, tbaLfndefIned . 

tbaHaltFromLeftH tbaHaltFroniRight. 
tbaBounceLeft * tbaflounc eRight. 
tbaBounceLeftChange, tbaBounceRlghtChange * 
tbaThruLeft. tbsThruRight. 
tbaThruLeftChange. tbaThruRightChangE* 
tbaThriiLeftOptimlzed, tbaThriiRightOptijiii.zed, 
tbaThniLeftChangEOptitnlzEd. 
tbaThruRightChangeOptimized \ NBitActionRoutines; 

typedef struct MactoNTMRule [ 

NBitActionRoutines action; 
unsigned char newSymbol: 
unsigned short ruleCount; 
struct MacroNTMRule 'nevState; 

/' set current state to newStatc when this rule fires 
] KacroNTMRule: 


ist pkice 

20 points 

2nd place 

10 points 

3rd place 

7 poinLs 

4th place 

4 points 

5ih place 

2 points 

finding bug 

2 points 

suggesting Challenge 

2 points 


typedef struct TapeSegment 1 
unsigned int symbol; 
unsigned int Exponent; 
struct Tapesegment *left**right; 
I TapeSegment; 


GLOBAL VARIABLES 

static QptimizedTMRule opti[nizedTMRules[512] ; 
static unsigned int highestState; 

static MacroNTMRule rules[256*2*256]; 


Here is Claes' winning Busy Beaver solution: 


BusyBeaverc 
Copyright © 2000 
Claes Wihlborg 

^include <Btdiq,h> 
//include <stdlib.h> 
//include <string*h> 

//include "'BusyBeaver ,h'' 


static unsigned int nBit, maxBltr 

//define tapeOim 1520 
static int nxtTapElx; 

static TapeSegment tnyTape [tapEDim] . *f reeSegment* 
‘rightmostSegment, 'leftmostSegment; 


static unsigned char 'TheTapeCenter; 

static ulong allocatedLeft* maxALeft* allocatedRight. 

maxARight: 

static ulong numberOfIsOnlnputTape: 


static int aLotOfZeroes[] 

0*0.0*0.0, 

0 . 0 . 0 . 0 . 0 . 

0 * 0 . 0 * 0 . 0 * 

0.0*0.0.0* 


= [ 

0,0.0*O.Q. 


0.0,0*0.0. 


0*0.0,0*0. 0.0*0*0*0* 

0 . 0 . 0 . 0 * 0 . 0 . 0 , 0 * 0 * 0 . 
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0 * 0 . 0 , 0 * 0 , 


o.o*o*a*o* o*o*o*o*o. 0*0.0.o*o* 0.0*0.0*0 


inDir = kMoveLeft^ 


0 . 0 * 0 . 0 * 0 * 0 * 0 * 0 . 0 * 0 * 0 * 0 . 0 . 0 * 0 * 0 . 0 * 0 . 0 * 0 . 

0 * 0 , 0 . 0 . 0 . 

0 . 0 * 0 . 0 . 0 . 0 * 0 . 0 * 0 . 0 . 0 . 0 . 0 . 0 * 0 * 0 . 0 . 0 . 0 . 0 . 

0 . 0 . 0 . 0.0 l\ 


FUNCTION PROTOTYPES 

static Boolean CreateOptmlzedTMRulesC 

TMRulo theTMRul e s [] , /" contains the rules for your BB machine 

7 

ulong numberOfTMRules): 

static void createNbitMacroRuls( unsigned int inSymbol* 
MactoKTMRule ‘InState ); 

static Boolean MoreSeginentsf void ) ; 
static TapeSegment ‘GetFreeSEgment£ void ): 
static TapeSegment ‘expandLeft( void )j 
static TapeSegment *expandRight£ void ): 

static Boolean runNBltTurlngMachine( 
uiong *nuniberOf IsGenerated. 
ulong ^nunibetOfRulesExecuted 


CrcateOptmizedTMRules 

static Boolean CreateOptmizedTMRules( 

TMRule theTKRuIes [] . /* contains the rules for your BB machine 

V 

uiong nuniberOfTMRules) 

I 

unsigned int 1,state *inputSymbol: 

OptlinizedTHEule ‘destRulej 

highestState ^ 0: 

memsetC optimizedTMRules* 0x00* 

512*elzeofCOptlmizedTMRuleJ ); 

for(1^0: i<numbfirOfTMRuleE: 1++) 
f 

if £(state “ theTHRules[1].oldState) > highestState) 
highestState = state: 

destRule = optimizedTMRules + ((theTHRules[i].oldState 

« X) + 

(inputSymbol=theTMRules[i].inputSymbol)): 

if tdestRule->actlon 1^ obaNotYetDefined) 

( 

printfC”State* %d Input; %d multiply defined\n"* 
theTHRules[i].oldState.inputSymbol): 

return false: 

} 

d€stRule->newState = optimizedTMRules + 

(theTHRules[i].newState 

« 1 ); 

deatRulfi’faction = obaHalt + 

3 *theTHRules[i].moveDirection: 

if (InputSymbol != theTHRulesti].OutputSymbol) 
if £ theTHRules tlj . InputSyinbol} destRule- 
>action+^2; 

else destRule->action-H': 

I 

return true; 


cn^tcNbitMacroRule 

static void createNbitHacroRule( unsigned int InSymbol* 
MacroNTMRule *lnState ] 

! 

int mySymbol = inSymbol; 
int bit; 

OptimlzedTMRule '‘state; 
int iState: 

OneBitActionRoutines action: 
int ruleCount " 0: 

MoV eDir inDir.outDir; 

iState “ (instate - rules) » nBit: 

state = optlmizedTHRules + £lState S Dxfffe): 

if (iState S 1) 

I 

bit = 1; 


1 

else 

1 

bit = maxEit: 
inDir = kMoveRlght; 

I 

loop: 

ruleCount++: 

if £mySymbol & bit] 

( 

action = state [1].action; 
state = state[1].newState: 

J 

else 

( 

action = state->action; 
state = state->newState: 

1 

switch (action) 

( 

case obaHotYetOeflned: 

instate->ruleCount = ruleCount; 
instate->newSyinbol = mySymbol; 
instate->action = tbaUndefined; 
return: 
case obaLeft; 

if ({bit «" 1) <= inaxBit) goto loop: 
break; 

case obaLeftSet; 

mySymbol |“ bit; 

if ((bit <<" 1) <" maxBit) goto loop: 
break: 

case obaLeftClear: 

mySymbol ^ T - bit: 

if ((bit «= 1 ) <= maxBit) goto loop; 

break: 

case obaHalt; 

instate■>ruleCount " ruleCount: 
instate->newSymbol = mySymbol; 
instate->action = (inDir = kMoveRlght)? 

tbaHaltFromLeft ; tbaHaltFromRight; 

return: 
case obaHaltSet: 

mySymbol |“ bit; 
instate->ruleCount = ruleCount; 
instate->newSymbol ^ mySymbol: 
instate->actlon = (inDir = kMoveRlght)? 

tbaHaltFromleft : tbaHaltFromRight; 

return; 

case obaHaltClsar: 

mySymbol &= -1 - bit; 
instate-)ruleCount “ ruleCount; 
instate->newSymbol ^ mySymbol: 
instate->action ^ (inDir ^ kMoveRlght)? 

tbaHaltFromheft ; tbaHaltFromRight; 

return: 

case obaRight: 

if (bit »= 1) goto loop: 
break; 

case obaRightSet; 

mySymbol N bit; 

if (bit 1) goto loop; 

break: 

case obaRlghtClear: 

mySymbol &= -1 - bit: 
if (bit >>= l) goto loop: 
break: 

) 

instate->ruleCount = ruleCount: 
instate->newSymbol = mySymbol: 
instate-)action " tbaBounceLeft; 
if (Ibit) 

( 

outDir ^ kMoveRlght: 
instate - >action-H'’ 

I 

else 

I 

outDir kHoveLeft; 

state++: 

1 
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if CraySymbol != inSymbol) 

Instate - >actioti 2: 

instate->newState ^ ((state * optimizedTHRules) « nSit) + 

rules: 

if (outDlr ^ iuDir) 

f 

Instate->actiDn += 4; 

if ((state - optimzedTMules) = IState) 
instate->actiQn 4: 

] 


return; 


MorcSt^cnts 

static Boolean MoreSegnientst void ) 

I 

int end: 

if (nBit = 6) return false: 
if (nxtTapelx < tapeDim) 

end = nxtTapeIx + 149: 
freeSegment = inyTape + nxtTapeIx: 
do 

( 

myTape[nxtTapeIx] .right = myTape + nxtTapeIx t 1; 

] 

while (-HuxtTapelx < end); 
my Tape [nxtTapeIx++].right * 0: 
return true; 

1 

// prmtfif‘‘St^ent5fioito]!!r\n”>; 
return false: 

1 


CictFrrcScgmcm 

static TapeSegment '‘GetFreeSegment { void ) 

t 

TapeSegment *tmp: 

If (freeSegment || MoreSegmentsC)) 

mp = freeSegment: 
freeSegment = trap->rlght: 
return tmp ■ 

I 

return 0: 


cxpandtcri 

static TapeSegment ‘expandLeft( void ) 

[ 

ulong delta: 

TapeSegment *tmp. ^newCurrent. *oIdLeftraaat: 
unsigned char *p.‘p01d: 
ulong oneCount, oldValue: 

if {[(delta - (((maxALeft - allo-catedLeft) ,>100) 7 

300 : (maxALeft - allocatedLeft)))) 

return 0: 

allocatedLeft delta: 
p = TheTapeCenter - allocatedLeft: 

if (1 (newCurrent = GetFreeSegmeiit ())) 
return 0: 

newCurrent-)left = 0: 
oldieftinost = leftraostSegment; 
leftmostSegment ” newCurrent: 

if (jmemcmpC p. aLotOfZeroes. delta)) 

I 

newCurrentsymbol = 0: 

newCurrent->exponent = 8*delta / nBit; 

] 

else 

If (nBit = 8) 

f 

newCurrent->symbol == *p: 
newCurrent->exponent = 1: 


pOld = p + delta: 
while (++P < pOld) 

( 

if C*p = newCurrent')symbol) 

I 

nevrCur rent - >exponent++: 

1 

else 

( 

tmp = newCurrent: 

if ([(newCurrent = GetFreeSegment()}) 
return 0: 

newCurrent-)Left = tmp: 
tmp-) right = newCurrent: 
newCurrent->symbol = *p: 
newCurrent-)exponent “ 1: 

1 

1 

tmp = newCurrent: 
do 

I 

If ((oldValue = tmp->symboi} 1=0) 

[ 

oneCount = 0: 
do [ 

+-l-oneCount; 

I while (oldValue = oldValue & ( oldValue - 1 )): 
numberOflsOnInputTape ^ oneCount*tmp->exponent: 

] 

I 

while (tmp = tmp-)left); 

] 

eleernBit^iV 

f 

return 0: 

I 

newCurrent-)right - oldLeftmost; 
if (oldLeftmost) 

[ 

oldLeftmost-)left = newCurrent; 

I 

else 

! 

rightmostSegment = newCurrent: 

1 

return newCurrent; 


oxpandRiglit 

static TapeSegment ^expandRlght( void ) 

[ 

ulong delta: 

TapeSegment ^tmip. ‘newCurrent. ‘oldiUghtmost: 
unsigned char *p.‘p01d: 
ulong oneCount. oldValue; 

if (J(delta = (((maxARlght - allocatedRight) )300) 7 

300 : (maxARight - allocatedRight)))) 

return 0: 

pOld = TheTapeCenter t allocatedRight: 
allocatedRight -i^ delta: 

if [!(newCurrent = GetFreeSegmentO}) 
return 0: 

newCurrent-)right = 0: 
oldRightmost ^ rightmostSegment: 
rightmostSegment = newCurrent; 

if ([memcmp( pQld, aLotOfZeroes, delta)) 

f 

newCurrent-)symbol = 0; 

newCurrent-)exponent “ B*delta / nBit: 

I 

else 

if (nBit = 8) 

i 

p = pQld -t- delta -1: 
newCurrent->symbol = *p; 
newCurrent-)exponeint = 1: 
while (“p >= pOld) 

1 


44 


Programmer's Challenge 


MAcfFECH • December 2000 









OpsnBase SQL 6.5 

The high-performance 
Database for MacOS X 



}penBase Features 

JDBC Driver 


We proem over 2 milim 
msuctions each day. 
^penBase performance has 
Bert outstanding.'* 

VghiArnvahMtn 


With over 2 Million Transactions per day, FlightArrivals.com flies witti OpenBase SQL 

Take OpenBase SQL for a Test Flight Today! ^ 

Get Your FREE Developer's License at www.openbase.com OpenBase 


if {*p = newCurrent - >EyTiibcil] 

I 

newCurrent->esponent++; 

1 

else 

I 

tHrp “ newCurrent i 

if (E [newCurrent = Geti’teeSegineiit ())) 
return 0: 

newCurrent*>rlght - tmp: 

tmp-)'lGft = nGwCurrentj 

newCurrsnt->fiyjnbol = *p: 
newGurrent - > exp orient - I ; 
f 

t 

tmp = newCurrent: 
do 
[ 

if [(oldValue = tmp->synbol] EK)) 

f 

oneCount = 0; 
do i 

++oneCount; 

\ while (oldValue = oldValue & (oldValae-l)) ; 
numb er0 f 1E Dnl nputXap e += oneCount * tmp - > siKp onent; 

[ 

] 

while (tmp = tmp-fright): 

1 

else/*nBiN^V 

f 

return 0; 

} 

TiewGurrent->lGft oldRightmoEt: 
oldlRightmost->right = newCurrent: 
r e turn newCn r r ent: 


run NBiLiuringMachiiic 

fitntic Boolean runNEitTuringMachine( 
u1ong *numberOflsCeneratedn 
uiong *numberOfRulesExecuted 

) 

I 

// IxjcjI daia aitits 

nlong oneCount; 
ulong ruleCount = 0: 
int oldValue.i; 

MacroNTMRiile ’state; 

Tap e S e gment * cur rent S egment. ’tmp: 

Boolean resultat = false: 

//Init 

’nuntberOflsGenerated - 0: 
numberOfIsOnInputTape = 0; 

memset( rules ^ 0x00, 

(highestState+l) *2* [l'C<nBit) *alzeof (MacroNTMRule) ) : 
state = rules; 

for (i=0;i<19:i++) 

I 

myTape [i] ►right = inyTape + i i 1; 

] 

myTape [19]. right = 0; 
freeSegment = myTape: 

rightmostSegment = 0: 
leftmostSegment = 0; 
allocatedLeft = 0; 
allocatedRight = 0: 

expandLeft(): 

currentSegment = expandElght(); 
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malnLoop: 

state += currentSe^ent-^symbol; 

loop: 

ruleCount += state-)ruleCount: 
switch (state"faction) 
i 

case tbaNotYetDefined: 

createNhitMacroRuie( currentSegment-^symbol * state ); 
goto loop: 

case tbaUndefined: 

goto avslutai 

case tbaHaltFromLeft: 

if (currentSegment-)exponent ) 1) 

{ 

tinp - currentSegment; 

if ([(currentSegment = freeSegment)) 

[ 

if (IMoreSegmentsO ) goto avsluta: 
currentSegment = freeSegment; 

I 

freeSegment = currentSegment-)right: 

currentSegment-)left = tmp->left; 

currentSegment-)left->right = currentSegment; 

currentSegment-)right = tmp: 

tmp->left - currentSegment: 

cu r rent Se gment-)e xp onent - 1: 

tmp-)exponent—: 

) 

cur rent Segnient-)symbol = state->newSymbol: 
break: 

c aa e tb aHa11F romRlght: 

if (currentSegment->exponent > 1) 

[ 

tmp = currentSegment: 
if {[(currentSegment - freeSegment)) 

[ 

if ([MoreSegmentsO ) goto avsluta: 
currentSegment “ fresSegment: 

\ 

fresSegment = currentSegment->right; 
currentSegment-)left ” tmp; 
currentSegment-)right tmp-)right: 
tmp->right->left = currentSegment; 
tmp-)right = currentSegment; 
currentSegment-)exponent = 1; 
tmp-)exponGnt—; 

I 

currentSegment )symbol ” state■knewSymbol: 
break; 

case tbaBounceLeft: 

state = state■)newEtate; 
currentSegment = currentSegment->left: 
goto mainLoop; 

case tbaBounceRight: 

currentSegment - currentSegment-)right: 
state = state■>newState: 
goto mainLoop: 

case tbaBounceLe ftChange: 

if (currentSegment-)exponent > 1) 

f 

tmp = currentSegment: 
if ([(currentSegment = freeSegmentJ) 

( 

if (]MoreSegmentsO) goto avsluta: 
currentSegment — freeSegment; 

J 

freeSegment = currentSegment->right; 
currentSegment-)left = tmp-)ieft; 
currentSegment-)right = tmp; 
tmp-)left-)rlght = currentSegment; 
tmp->left = currentSegment; 
currentSegment-)exponent - 1; 
tmp-)exponent”: 

] 

currentSegnient->symbol = state-)newSyi:nbol: 
state = state-)nevState: 
currentSegment = currentSegment-)left; 
goto mainLoop: 


case tbaBoiinceRi ght Change: 

if [currentSegment-)exponent > 1) 

f 

tmp “ currentSegment; 

if (! (currentSegment = freeSe^ent)) 

f 

If ([MoreSegmentsO) goto avsluta; 
currentSegment = freeSegment: 

I 

freeSegment = currentSegment-)right; 
currentSegment')left = tmp: 
currentSegment-)right = tmp->right: 
tmp->right-)left = currentSegment; 
tmp -) r ight “ cu r r ent S egment; 
currentSegment-)exponent ” 1; 
trap-)exponent—; 

1 

currentSegment-)symbol = state-)newSymbol; 
currentSegment = currentSegment-)right: 
state - state-)newState; 
goto mainLoop: 

case tbaThruLeft: 

if (currentSegment-)exponent ) 1) 

[ 

tmp = currentSegment: 
if ([{currentSegment - freeSegment)) 

( 

if (IMoteSegments0) goto avsluta; 
currentSegment - freeSegment: 

] 

freeSegment " currentSegment-)right: 
currentSegment->left = tmp; 
currentSegnient->right - trap->right; 
tmp-)right-)left = currentSegment; 
tmp-)right - currentSegment; 
currentSegment->exponent = 1: 
trap-)exponent—; 

I 

state state-)newState: 
if (currentSegment = currentSegment-)left) 
goto mainLoop: 

if (currentSegment = expandLeft()) goto mainLoop; 
break: 

case tbaThruRight: 

if (currentSegment’)exponent ) 1} 

\ 

tmp - currentSegment: 
if ([(currentSegment = freeSegment)) 

f 

if [[MoreSegmentsO) goto avsluta; 
currentSegment = freeSegment; 

I 

freeSegment = currentSegment-)right; 
currentSegment-)left = tmp-)left; 
currentSegment-)right = tmp; 
tnip->left->right = currentSegment: 
tmp->left = currentSegment; 
cur ren t Se gment *)exponent = 1: 
tmp-)exponent—; 

1 

state = state-)newState; 

if [currentSegment = currentSegment-)right) 
goto mainLoop: 

if (currentSegment “ expandRightO} goto mainLoop: 
break: 

case tbaThruLeftChange: 

if tcurrentSegment-)expQnent ) 1) 

I 

tmp ^ currentSegment; 
if {[(currentSegment = freeSegment)) 

[ 

if ([MoreSegmentsO) goto avsluta: 
currentSegment = freeSegment; 

I 

freeSegment === currentSegti]ent-)ri ght; 
currentSegment->left = trap: 
currentSegment-)rxght = tmp->right: 
trap-)right-)left = currentSegment; 
tmp->right = currentSegment; 
cu r rent S e gmen t-)exponent - 1: 
trap-)exponent—; 
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I 

currentSegment-) symbol = atatO’>newSyiiiboi: 
state = state->newState; 
if (currentSegment = curirentSegnient->left) 
goto mainLoop: 

if (currentSegment ^ expandLeft()) goto madnLoop: 
break; 

taae tbaThruRightChange; 

if Current Segment-) exp orient > 1) 

1 

tmp ^ currentSegment: 

if (!(currentSegment = freeSegment)) 

t 

if (IMoreSegiaents C)} goto avslnta; 
currentsegment = freeSegment: 

f 

freeSegment = currentSegment■)right: 
currentSegment->left = tiiip->leftr 
currentSegment-)right = tmp; 
mp->left->right = currentSegment: 
tmp')left = currentSegment; 
currentSegment-)exponent ^ 1: 
tmp->exponent-: 

) 

currentSegment-)symbol = state->newSymbol: 
state = state->newState: 

if (cur rent Segment = currentSegmentO right) 
goto malnliOop; 

if (eurrentSegment = expandRlght()) goto mainLoop; 
break; 

case tbaThruLeftOptimized: 

while ((tmp = currentSegment‘>left) && 

(cur rent Segment-) symbol “ tmp'■> symbol)) 

I 

cur rent Segment->exponeTit 4= tmp->exponent: 
tli^}-)rlght = freeSegment; 
frees egment =■ tmp: 
eurrentSegment->left = tmp->Left; 
if (eurrentSegment->left) 
eurrentSegment->left->rlght “ eurrentSegment: 
else 

leftmostSegment = eurrentSegment; 


1 ); 


malnLoop: 


mleCount += state->ruleCount* 

(cur r entSegment - > exponent - 

state = state->newState; 
if (eurrentSegment = currentEe^ent->left) 
goto maihLoop: 

if (eurrentSegment “ expandLeft ()) goto 
break: 


case tbaThruRightOptimlzed: 

while ((tmp ^ currentSegment->right3 

(currentSegment-)symbol = tmp- 


>Eymbol)) 

I 


eurrentSegment-)exponent += tmp-)exponent; 
eurrentSegment->r±ght ^ t3iip->right; 
tmp->rlght = freeSegment: 
frees egment ^ trap; 
if (currentSegment-)right) 

eurrentSegment-)right->left = 

eurrentSegment; 

else 

rlghtmostSegment = eurrentSegment; 

} 

ruleCount 1= state-)ruleCount* 

(eurrentSegment->exponent- 


13; 


state = state-)newState; 

If (eurrentSegment ® eurrentSegment)right) 
goto malnLoop: 

if (eurrentSegment = expandRlght()) goto 


malnLoop: 

break; 


case tbaThruLeftChangeOptiirlaed; 

while ({trap = eurrentSegment-)left) 
(eurrentSegment-)symbol = 

>symbol3 3 

I 




tmp- 


cutrentSegi!tent->exponent += tmp->exponent; 
tmp->rlght = freeSegment; 
freeSegment trap; 
eurrentSegment-)left = trap-)left; 
if (eurrentSegment->left) 


Fight Boredom 

Let’s face it: Much of programming is boring 
and repetitive. Well, that’s where the right 
tool can save days, weeks, or even months 
of your valuable time. 



Model- View-Controller 

AppMaker’s generated code uses the MVC 
paradigm. It separates the user interface 
from application logic, making code easier 
to write. You deal only with abstract data; 
AppMaker takes care of the user interface. 


AppMaker 

Your Assistant Programmer 

AppMaker makes it faster and easier to make an 
application. It’s like having your own assistant 
programmer. You point and click to tell 
AppMaker the results you want, then it 
generates “human, professional quality code” 
to implement your design. 


ScriptBbie AppHcBtions 

AppMaker generates the 'aete^ resource and 
generates code to access your data 
(Properties and Elements in the Apple Event 
Object Model) and to handle Events. 

Just $199 from www.devdepot.com B*0*w*E*R*S 

Development 

P.O. Box 929, Graniham, NH 03753 • (603) 863-0945 • FAX 863-3857 
bo wersdev @ ao Lc o m • h tip: //membe rs .ao 1 .com/bo wersdev 
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cur rent Segment= currentSe^ent: 
else 

lefanostSegment = cur rent Segment; 

} 

curreiitSegment->symbQl = BtateOnewSymbnl: 
ruleCount state->ruleGount“ 

(currentSegment->exponent-i); 
state = state ’ >newState:: 
if (currentsegment ^ currentSeginent->left) 
goto raairiLoop; 

if (currentsegjaent = expandLeft ()) goto mainLoop; 
break: 

case tbaThruRlghtCbangeOptlmized; 

while CCtmp = currentSegment->rig^t} 

(currentSegment->symbol = tmp->symbol)) 

f 

currentSegment'^exponent += tmp-^exponent: 
currentSegment->right = tmp>right: 
tjnp-> right “ free Segment; 
freeSegment = tmp; 
if (cu r r ent Segment -> right) 
cur rent Segment - >right ^ >lef t ^ cur rent Seg;ment; 
else 

rightmost Segment = currentSegment; 

f 

currentSegment■>symbol * state->newSymbol: 
ruleCount state*>ruleCount‘ 

(currentSegment->exponent'1): 
state " state■>newState; 

if (currentSegment = currentSegment->right) goto mainLoop: 
if (currentSegment = expandRl^t()} goto mainLoop: 

] 

if (currentSequent) 

[ 

teeultat “ true: 

I 

avsluta; 

•numbetOfRulesExecuted = ruleCount; 

for (currentSegment = leftmostSegment: currentSegment: 

currentSGgment=currentSegment■>right) 

I 

if ((oldVaiue - currentSegment->symbol) 1=0) 

i 

oneGount = 0; 
do I 

++oneCount: 

J while (oldVaiue = oldValue & (oldValue 1)): 

*numberOfIsGenerated i= oneCount*currentSegment'>Gxponent; 

1 

) 

// bug in following line corFccEcd by JRB, dEJt'snl affea results 
// numlx.-fC>fls£kncnilcU-= numbcKlflsOnlnputTape; 

*nujiiberOflEGenerated -= numberQfIsOnlnputTape; 

return resultat; 


kunluring-VLidiine 

Boolean /* ictum true l()rsuccess V RunTUringMachine ( 

TMRule theTMRulesLI . 
r conuiins the rules Ibr tout Ull nviidiirie 7 
ulong numberOfTMRules. 
r llic numiKT tjf rules in die riM Rules 7 
ulong numBytealuHalfTape. 

/* ttdfsizic of thc 'Mnite’ TurtJig Madiinc mpe 7 
unsigned chax •tra.Tape. 
f* pointer to preaBexiitcd Hiring Madiine Uipc sttJtuge 7 
f* Fadi byte ctmtains 8 cape symbols, each symbol is 0 eit L 7 
/*'nie tipc extends from tmTapcl-numBytesinHalfRipe] to 
tmTape [ouitdiytcilnHalf Ripe - 1 j V 
/•Tape jx)sition 0 is (toiTapejOl & (IxBO), 
tape- positit>n I Ls (tmTape[0] & 0x40) 
tiipe poiSftiEin -1 is (tiuTapef-l] & OxOliCtc. 7 
ulong 'numberOfIsGenerated, 
r return the number of Is placed on die tape 7 
along *numberOfRulesExecuted 

/* return die number of rules executed wlien running BB, indudipg the liai( nile V 


// Local data areas 

unsigned char *p: 
along myDoubleSymbol; 

Boolean resultat: 

Tape S e gment 'cur r ent S e gment; 

// Init daLi areas 

If (ICreatGOptmizGdTMRules( theTMRules , numberOfTMRules)) 

f 

return false: 

} 

TheTapeCenter = tuiTape; 

nBit = 6: 
maxBit = 0x20: 

maxALeft = numBytesluBalfTape - numByteslnHalfTape^B: 
maxARight = maxALeft: 

resultat = tuuNBitTuringHachine ( numberOf Is Gene rated* 
numbsrOfRulesExecuted ): 

if (resultat) 

i 

p ^ tmTape - allocatedLeft: 
currentSe^ent ^ leftmost Segment; 

//define CHECK„SEGKENT \ 

if {-{currentSe^nt^exponent) = 0} V 

currentSegmefit“currentSeginent '> right 

while (currentSegment) 

( 

iiiyDouhleSyinbol = currentSegment■>symbol « IS; 
CRECK^SEGMENT: 

myDoubleSymbol currentSegment->symbol « 12; 

CHECR_SEGKENT; 

myDoubleSymbol currentSegment->aymbol « 6; 

CHECPLSEGMENT: 

myDoubleSymbol |=^ currentSegment'>symbol: 
CHEGK.SEGMENT: 

= myDoubleSymbol»16: 

•p+f - myDoubleSymbol»8; 

*p++ - myDoubleSymbol; 

1 

return true; 

1 

nBit - B; 
maxBlt = 0x80: 

maxALeft ^ numBytesInHalfTape; 
snaxARlght = maxALeft; 
nxtTapeIx = 20: 

resultat “ runKBitTuringJ1achlne( numberOfIsGenerated. 

numberOfRulesExecuted ): 

p * tmTape - allocatedLeft; 

for (currentSegment leftmostSegment; currentSegment: 

cur rent Segment^currentSegntent - >rlght) 

I 

memset( p* cur re nt Segnient-> symbol, currentSegment- 
>exponent ): 

p ^ currentSegment->exponent: 

1 

return resultat: 


m 


48 


Programmer’s Challenge 


Ma<Uf.ch • Degembek 2()00 





QUICKTIME 

TOOLKIT 


by Tim Monroe 


Timecode 


Using QuickTime's Timecode Media 
Handler 

Introduction 

It's often useful — especially when editing some video or 
audio media — to be able to assign a precise time stamp to a 
place in a stream of media data. In 1967, die Society of Motion 
Picture and Television Engineers (SMl^TE) introduced a metiiod 
for doing this, called timecoding. Timecoding Ls a way of 
putting time stamps (called iimecoTies) on recorded media such 
as film, video, sound, and the like. 

QuickT'ime, of course, iias its own meLficxis of specifying 
times witliin a movie, using time bases, time values, and time 
scales. (See “Movie Controller Potpourri'’ in MacTech, February, 
1999 for a preliminary discussion of these concepts.) Hut 
QuickTime also supports storing and displaying SMPTH 
limecodes. Figure 1 shows a frame of a QuickTime movie with 
a Limec:ode value displayed Ix^low the video track. 



Figure 1 . A movie frame tvitb timecode displayed. 


Timecode is displayed using an eight “digit, 24“hour 
clock that looks like this: hh\mm\ssjf The digits represent 
(from left to right) hours, minutes, seconds, and frames. 
As you can see, the frame displayed in Figure 1 is exactly 
14 seconds from the beginning of the movie (assuming 
that the movie began ai timecode 00:00:004)0). The actual 
timecode values of a specific QuickTime movie can be 
synthesized by the computer or captured along with the 
source material 

In this article, w-e’ll take a look at using timecodes in 
QuickTime movies. Timecodes are stored in timecode 
track.s, which are created and managed using the timecode 
media handler, The timecode media handler is extremely 
ea.sy to work with; it provides a grand total of 11 functions 
(of which we’ll use only 7 here) and requires us to work 
with only a handful of data structures. In fact, there is only 
one mildly difficult concept well need to understand; the 
notion of drop-frame timecode. Well begin l^y 
investigating the standard timecode formats, and then 
we’ll move on to seeing hoW' to create and manage 
timecode tracks in QuiekTinie mewies. 

Our sample application this month is called 
QTTimeCode; its Test menu contains the timecode-specific 
commands. Figure 2 shows the Test menu for movies that 
do not contain a limecode track. 


Test 


Add Timecode Track... 


Remoue Timecode Tracks 

m2 

Shom Current Timecode 


Show Timecode Source 


Toggle Timecode Display 



figure 2. I he Test menu of QTTimeCode. 


Hm Monroe is happy to announce the birth of a baby lizard. Libra, the son or daughter of Sean and Avril, was bom in early October. You can send 
reptile layette items to him at monroc@applc.com. 
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Figure 3 shows the Test menu for movies that do contain 
a timecode track. 


Test 


Rdd Timecode Trade... 

n\ 

Remoue Timecode Tracies 


Show Current Timecode 

313 

Show Timecode Source 

334 

Toggle Timecode Displag 

335 


Figure 3- The Test menu of QTTimeCode. 


Timecode Standards 

As weVe seen, timecode is expressed using an eight- 
digit clock, where the rightmost two digits represent a 
frame number There are four standard frame rates used 
commercially around the world, so there are (our 
standard timecode formats: 

• Most film produced in the Llnited States uses a 
standard of 24 frames per second (fps). 

• Most film produced in Europe and Australia uses a 
standard of 25 fps, established by the European 
Broadcasting Union (EBU); 25 fps is also used for PAL 
or SECAM video and television. 

• The SMPl’H standard for American black-and-white 
television uses 50 fps. This frame rate is also 
commonly used for audio and CD mastering. 

■ American color television and systems based on it (such 
as NTSC video) use a standard of 29.97 fps. Thi.s rale is 
the result (]f certain technical decisions made when 
converting from black-and-white to color television. 

The oddball here is the SMPTE standard for American 
color television and NTSC video, which uses a frame rate 
of 29.97. This is close enough to 30 that people typically 
ctmsider American color TV' to have a frame rate of 30 fps. 
But 29.97 i.sn't exactly 30, and the difference can add up. 
For instance, over a period of one hour, a 30 fps movie 
will display 108,000 frames, whereas a 29.97 fps movie 
wall display 107,892 frames. This means that, if w^e use a 
30 fps timecode to display the time of a 29.97 fps movie, 
the movie would be 108 laames (or about 3.6 seconds) 
longer than a movie that has exactly 30 fps. That is to say, 
by the time a 29.97 fps movie gets to 108,000 frames, 1 
hour and 3-6 seconds has elapsed. 

For most purposes, an extra 3.6 seconds per hour is 
pretty insignificant. But on commercial TV, time is money. 
For example, ABC Broadcasting is expected to charge 


$2.2 million for a 30“Second advertisement during the 
2001 Super Bowl, In that case, 3.6 seconds is worth about 
$264,000. So it’s sometimes important to get timecode 
values exactly right. 

To ensure that 30 fps timecodes displayed by a 29.97 fps 
movie exactly match the time on a wall clock, SMPTE 
defined drop-frame Hmecoding, according to which two 
frame numbers are dropped at the start of every minute, 
except for every minute that is evenly divisible by ten. (For 
example, the timecode value 11:31:59:29 is immediately 
followed by 11:32:00:02,) So, over the course of one hour, 
108 frame numbers will be dropped, w'hich is exactly what 
is needed to bring the 30 fps timecode display into 
synchronization with a wall clock. In spite of the name 
(^'drop-frame timecode”), no video frames are dropped. 
Rather, frame numbers are dropped from the timecode 
display so that the timecode stays in synch witli a wall clock. 

When drop-frame timeccxle is l^ing used, it’s conventionaJ 
to use a comma (T) or u semicolon (T) to separate the seconds 
digits from the frames digits. Figure 4 shows a QuickTime 
movie that uses drop-frame timecode. 



Figure 4, A movie frame with drop-frame timecode. 

Keep in mind that in a timecode, the rightmost two 
digits represent a frame number, not (say) hundredths of 
a second. This is wonh remarking, if only because there 
are occasions where QuickTime does use the rightmost 
digits to represent fractions of a second. For instance, in 
the previous QuickTime Toolkit article (/'Word Is Out” in 
MacTeeb, November 2000), w'e saw that the text movie 
importer recognizes a number of text descriptors, one of 
which is a timestamp indicating the time at which the 
imported text sample is to begin. In tliis case, the 
rightmost digits represent a number of time scale units. 
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Programming Doesn't Have 
To Be This Difficult. It's REALbasic! 



REALbasic is the award-winning, visual, 
object-oriented BASIC development 
environment for the Macintosh. 


Use REALbasic's visual interface builder and platform-independent 
language to build native, compiled—^not interpreted—professional 
quality applications in a fraction of the time it would take in C/C++. 
Because our language is platfonn-independent you only need to 
write a single set of code to create applications for both Macintosh 
and Windows. Leverage your C/C++ experience to extend 
REALbasic's capabilities using shared libraries, Mac OS Toolbox 
and Win32 API calls or by writing cross-pktfoim REALbasic plug-ins. 


Create prototypes, Internet applications, database front-ends, even 
games with REALbasic! Its OOP language employs everything 


you'd expect from a modem development environment—^methods, 
properties, classes, subclassing, inheritance, constmctors and 
destructors, virtual methods, and more. The IDE supports multi¬ 
threading, extensibility, TCP/IP controls, plus multimedia and 
QuickTime tools, and support for standards such as SQL, ODBC, 
AppleScript, and XCMDs. You can even import Visual Basic forms 
and modules. 

Go to www.realbasic.com NOW to download a FREE 
trial version or call 512.263.1233. 


9 REALbasic 



MacPower 

Products of 
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Apple 

Design 
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*Free update for all owners of REALTiasic 2.0 and above REALbasic and the ft£ALba5ic Icngci ar? trademadcs of REAL Software. Inc. Apple and the Apple logo 
are trademarks of Apple Computer. Inc., registered in the U-S., used with permission All other trademarks are the property of their respective owners. 






Tlmecode in QuickTime 

QuickTime version 2,0 introduced the tiniecode 
media handier^ which we can use to create dmecode 
tracks in movies^ itide and show those tracks, get and set 
information about tirnecode tracks, and so forth. The 
timecode media handler supports both drop-fra me and 
non^drop-frame timecodes, as well as a simple counter 
(shown in Figure 5) 



figure 5 - A movie frame with a counter 

A timecode track specifies liming information lor one 
or more other tracks, which are typically video or sound 
tracks. To associate the timecode track witli a target track, 
tlie target track contains a track reference to the timecode 
track, (See the “Word Is OuC article f>nce again for a 
discussion of track references.) 

All of the QuickTime fvmctitjns for working with 
limeccKles take an instance of the timecode media handler 
as a parameter. Our sample application QTTimeCode 
creates a single timecode track in a movie, so we can call 
GetMovieindTrackType and GetMediaHandler to find a 
movie's timecode media handler, as shown in Listing T 

Listing 1: Finding a movie’s timecode media 
handler instance 


QTTC_G etTimeC o d eJVl e d laH !m d le r 

MediaHandler QTTC^GetTimeCodeMediaHandler (Movie 
theMovie} 

i 

Track myTrack = NULL; 

Media myMedia = NULL: 

MediaHandler tnyHandlet = NULL; 

// get the timecode tmek in the specified movie 
myTrack = GetMovieindTrackType(theMovle, 1, 

TlmeCodeMediaType . tnovieTrackMediaType) : 
if (myTrack t= NULL) f 


// get the timecode track's media and media handier 
TnyMedia ^ GetTrackHedla (tnyTrack) ; 
if (myMedia != NULL) 

rayHandler = GetMediaHandler(myMedia); 

1 

return(myHandler); 

] 

When the user selects the “Acid Timecode Track..." 
command in the Test menu of our QTTimeCode 
application, QTTimeCode displays the dialog box shown 
in Figure 6 to elicit some settings from the user. 



Figures 6. Q7TifneCode\s Timecode 
Opt urns dialog box. 

As you can see, QTfimeCodc allows the user to 
.specify the name of the media st>urce (which might be the 
name of the tape from which the videtj was digitized). 
The user can also indicate whether the liniecode should 
he displayed at all, and (if so) whether the timecode 
should be displayed belo’iv the video. QTTimeCode 
allows the user to specify the font in w^hieh the timecode 
is displayed and the starting time of the tirnecodes. 

It*s worth empha.sizing that a timecode track in a 
QLiickTiine movie does not affect the actual timing of die 
movie playback. QuickTimeks own timing facilities always 
determine the rate at which frames in a movie are 
displayed. If, for example, we play a movie back at twice 
its normal rate, the tirnecodes WK)uld also zip by at twice 
the speed of a wall clock. 

Timecode Tracks 

We add a timecode track to a movie in exactly the 
same way weVe added other kinds of tracks. The main 
difference, of course, is that the media type of the new 
track will be TimeCodeMediaType, To know how to add a 
timecode track to an existing movie, we need to know 
only two things: (1) the format of the data in a timecode 
media sample; and (2) the structure of a sample 
description for a timecode media sample. Let's tackle 
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these issues in reverse cirden WeUI alscj consider hc^w to 
set the placement of the timecnde track and cc^nfigure 
some of the text options. 


Creating a Timecode Sample Description 

A timecode sample descriptkm is defined by the 
TimeCodeDescription data type, like this; 


TimeCodeDescription | 
descSl^e: 
dataForraat 
resvdl; 


struct 
long 
long 
long 
short 
short 
long 
TiittGCodeDEf 
long 
I ; 


resvd2; 
dataRefIndex 
flags: 

tlmeCodcBef; 
srcRof[1]: 


The first five fields are common to all sample 
descriptions, and we need to fill in only the descSize and 
dataFormat fields: 

TimeCodeDescriptionKandle myDesc - NULL? 
long raySize; 

mySize = sizeof(TimeCodeDescription): 
myDesc = 

(TimeCodeDescriptionHandlejNewHandleClear(mySize): 
if CmyDeac == NULL) 
goto ball: 

^myDesc),descSize * mySize: 

{*•myDesc)*dataFormat ^ TimeCodeMadlaType: 


The flags field is reserved and should be set to 0. The 
timeCodeDef field is a timecode definition structure that 
contains information about the desired format of the 
timecode. A timecode definition structure is defined by 
the TimeCodeDef structure: 


struct TimeCodeDef 
long 

TlmeScale 

TlmeValue 

UIntB 

Uinta 


( 

flags: 

fTimeScale; 
frameDuration: 
numFrames; 
padding: 


typedef struct TimeCodeDef TimeCodeDef: 


The flags field of the TimeCodeDef structure contains a 
set of flags that specif)^ information about the formal of 
the timecode. Currently, these flags are defined: 


anum 1 

tcDropFrame 

tc24HourNax 

tcKegTimesOK 

teConnter 

1 ; 


= 1 « 0 . 

= 1 << 1. 

= 1 << Z 
- 1 « 3 


The tcDropFrame flag, of course, indicates whether the 
timecode Is drop-frame or non-drop-frame timecode. The 
tc24HourMaK flag indicates whether the hours digits return 
to 0 at 24 hours or keep advancing. The tcNegTimesOK 
flag indicates whether negative timecode values are 
allowed. Finally, the teCounter flag indicates whether to 
display the simple counter instead of a SMPTE timecode. 
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inyNameHandle = NULL; 


The numFrames field of the TimeCodeDef structure 
indicates the number of frames in each second of media 
data in the target track. If the simple counter is being 
displayed, this field indicates the number of frames that 
make up each increment of the counter. The frameDuration 
field indicates the duration, in time units defined by the 
ffimeScale field, of each frame in the target media. 

QTrimeCode keeps track of most of these settings by 
defining a set of global variables (which makes it easy to 
get information into and out of the Timecode Options 
dialog box). Using some of these globals, we set up the 
timecode definition structure as shown in Listing 2. 

Listing 2; Setting up a timecode def inition structure 

QfrC_AddTimeCode1'oMovie 

// set the timecode format information flags 
if (gUseTimeCode) { 
myFlagfi = OL: 
if (gDropFrameVal) 

myFlags 1= tcDropFrarae: 
if (glsN^g) 

myFlags [= tcNegTimesOK; 
if Cg24Hour) 

myFlags |= tc24HourMax: 

1 else I 

myFlags = teCounter; 

) 

myTCDef.flags = myFlags: 
myTCDef.fTimeScale ^ gTimeScale; 
myTCDef,frameDuration = gFrameDur: 
myTCDef . numFrames = gNumFratnes: 

The last field in a timecode sample description is the 
srcRef field, which is defined as an array containing a 
single long integer This field contains information about 
the source of the timecode values. As mentioned earlier, 
this is typically the name of the tape or other source of 
the media data from which the timecode values were 
originally captured. The interesting thing here is that the 
data in this field must be formatted in the same WTiy as a 
piece of movie or track user data. As a result, we can 
create the source information using QuickTime’s user data 
functions like NewUserData and AddUserDataText. But the 
source information is not stored in the same location as 
movie or track user data; instead, it's stored in the 
timecode sample de.scription itselfi The timecode media 
handler provides a function, TCSetSourceRef, that we can 
use to put the source information into the timecode 
sample description. Listing 3 show's how we set the 
source information for a timecode track. Notice that the 
user data item is of type TCSourceRefNameType, 

List ing 3: Se ttin g the source i nformation_ 

QTTC„ AddT irn eCodeToM o vie 

Us^rData rayUserData; 

inyErr ” NewUserData (ficinyUserData) ; 
if (myErr = noErr) i 


Handle 

myErr = PtrToHatid (SgSrcName [ 1] * ficmyNameHandle , 

gSrcName[0])i 

if (myErr = noErr) E 

myErr - AddUserDataText (myOserData, myNameHaiidle . 

TCSourceRefNameType* 1* langEnglish); 

If (myErr = noErr) 

TCSetSourceKefCmyHandler. myDesc. myUserData); 

I 

if {myNameHandle E“ NULL) 

DisposeHandle (myNaoieHandle) ; 

DlsposeUserData(myUserData): 

1 

Why isnT the source information stored as part of the 
track’s user data (in an atom of type ‘udtaO? Part of the 
reason is that there can be more than one timecode 
sample in a timecode track, and each sample may be 
associated with timecode information from a different 
source. So it makes sense to attach the source information 
to the timecode sample description. In any event, we 
really don't need to worry about where the source 
information is stored, since we shall always use the 
functions TCSetSourceRef and TCGetSourceRef to set and 
get that information. (For what it\s worth, QTTimeCode 
wall create only one timecode sample, w-hich spans length 
of the entire targei irack,) TCSetSourceRef updates the 
descSize field of the timecode .sample description, so we 
don't need to do this ourselves. 

Creating a Timecode Media Sample 

Now we need to see how to create a media sample 
for our timecode track. The sample description contains 
information about the format and source of the timecode. 
The start time and duration of the media sample indicate 
I lie start time and duratkxn of the timecode display. All 
that remains is to specify the timecode value of the first 
frame of the target track segment. That is to say, when the 
timecode media handler encounters a timecode sample, it 
needs to know what the timecode value is at that 
mcmienl. This is precisely what’s contained in a timecode 
media sample. 

A timecode media sample contains a long integer that 
specifies the timecode value of the first frame in the target 
track that is to have a timecode value associated whth it. The 
timecode value is stored as a frame number, which is 
converted automatically to a timecode value by the timecode 
media handler, llie timecode media handler provides 
functions for converting timecode values into frame values 
and iJice versa. To see how this works, let’s suppose that we 
want the first frame oi' a movie to have the timecode 
08:23:11;00. Suppose further that tlie four parts of tins 
timecode value are contained in the global variables gHours, 
gMinutes, gSeconds, and gFrames, Ultimately w'e want to call 
the function TCTimeCodeToFrameNumber to determine the 
frame number that we’ll put into the media sample. We 
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specif>^ the timecode value to TCTlmeCodeToFrameNumber by 
passing it a pointer to a time code record, defined tike this: 

union TiideCodeRecord [ 

TimeCodeTlme Zi 

TimeCodeCounter c; 

) ; 

typedef union TitneCodeRecord TlmeCodeRecord: 


This is a union that contains either a timecode time record 
or a timecode counter record: 

struct TiroeCodeTime [ 

UIntS hoursr 

UIntS minutes: 

UIntB seconds: 

UIntB frames; 

] ; 

typedef struct TimeCodeTinie TimeCodeTime: 

struct TimeCodeCounter [ 
long counter : 

typedef struct TimeCodeCounter TimeCodeCounter: 


Since weVe got a timecode value that we want to 
convert into a frame number, we'll use the t variant, like this: 

myTCRec,t.hours = (UIntS)gHoUrs: 
myTGRec*t.minutes ^ (Ulntd)gMinutes; 
myTCRec.t*seconds = (UIntS)gSeconds: 
myTCRec,t,frames “ (UIntS)gFrames: 
if (glsHeg) 

myTCRec.t.minutes |= tctNegFlag: 


Notice that the minutes field of the time code time record 
should have the bit tctNegFlag (namely, 0x80) set if the 
timecode value is to be interpreted as a negative value. 

We’re finally ready to create the timecode media sample 
data. Since AddMediaSample wants a handle to tlie media data, 
we need to allocate a relocatable block large enough to hold 
a long integer and then call TCTimeCodeToFrameNunnber to 
ctinvert the timecxxJc stored in myTCRec into a frame number. 
Then we need to easure that the frame number is stored in 
big-endian format, like this: 

myFramefiandle = (long ‘*)NewHandle(siseof(long)): 
if (rnyFrameflandle = NULL) 
goto ball: 

myErr = TCTimeCodeToFr^meNumber(myHandler, 

‘ ’myDesc) . tlmeCodeDef, 6tmyTCKec . 
’myFrameHandle): 

•*myFrameHandle = EndianS32_NtoB(**myFrameHandle): 

Then we proceed as usual, calling BeginMediaEdits, 
AddMediaSample, EndMediaEdits, and fnsertMedialntoTrack. 

Setting the Timecode Track Geometry 

For simplicity, the QTTimeCode application uses the 
first video track in a movie as the target track (that is, the 
track that contains a track reference to the timecode 
track), Well call GetTrackDimensions on the target track to 
get the desired width of the timecode track. For the initial 
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height of the timecode track, well use a predefined 
constant. Ideally, however, the height of the timecode 
track should depend on the height of the timecode 
display, which depends of course on the font and point 
si^e of the characters in the timecode display. We can 
retrieve information about the timecode display by calling 
TCGetDfsplayOptions, which returns information in a text 
optiom stmcture^ defined by the TCTextOptions data type: 


descent line (plus a couple of pixels of extra space). In 
some fonts, the numerals have no descenders, so this 
calculation will tend to make the timecode look out of 
center vertically within the timecode track. Devising a 
better algorithm is left as an exercise for the reader 

Now weVe determined the proper height and width 
for the timecode track. At this point, we can reset the 
track dimensions: 


Struct TCTextOptions { 


short 
short 
short 
short 
RGBColor 
RGBGolor 


txFont: 
txFsce: 
txSize: 
pad: 

foreColor: 
backColor: 


typedef struct TCTextOptions TCTextOptions: 


The txFont field contains the font number of the 
timecode display font. When setting Lip a timecode track, 
w'e want to do two things with this font. First, we want to 
reset the txFont field to the font number of the font that 
the user selected in our application's I'lmecode Options 
dial(}g box (see Figure 6 again). Then we want to measure 
that font to determine tlie rnaxiinum height for our 
limeccjde track. 

When the user closes the 1 iniecode Options dialog 
box by clicking the OK buUt>n, QTTimeCode gets the 
index and name of the currently-selected font by 
executing these two lines of code: 


SetTrackDlmenslons(myTrack. rayWldth, myTCHeight): 

Then, if the user has indicated that the timecode track 
should appear below the video track, we can reset the 
track matrix, like this: 

GetTr.ackMatrix(myTrack, imyMatrix): 
if (gDisplayEelowVideo) 

TtanslataHatrixC&niyMatrix. 0^ ayHeight) ; 
SetTrackMatrix{i!iyTrack, ^niyKatrix]; 

The timecode track is now positioned at the desired 
location with the appropriate width and height. 

We can configure the track to be displayed by calling 
TCSetTimeCodeFlaga with the tcdfShowTimeCode flag. 

TCSetTimeCodeFlags(myHandler, 

gDisplayTimeCode ? tcdfShovTlmeCode : 0, 
tcdfShovTlmeCode]r 


A Liniecode track must he enal)led in order for it to be 
displayed, .so we .should call SetTrackEnabled before 
calling TCSetTimeCodeFlags. 


gFoutliidex = GetCoutrolValLie (myControl) ; 
GetMenuItemText(rnyMenu, gFontIndex. gFontName): 


Then, when creating a timecode track, QTl'inieCode uses 
the font name stored in the gFontName global variable to 
find the appropriate font number: 

TCGetDi splayOptiong (myHandl er , &iiiyTextOptions) : 
GeuFKumCgFontHamG. SmyTextOptions.txFont): 
TCSGtDlsplayOptions (myHandler , 6(myTextOptlons) : 


Now we need to determine the maximum height of 
the timecode display. We can do this by getting a 
lepiesentative siring containing a timecode and then 
measuring that string in the current font, style, and size: 

// use the starting time to figure out the tiimensitms of track 
TCTimeCodeToSt ring(myHand1er, 

^myTCDef, SrayTCRec , tnyString) : 
TextFoiit CmyTextOptions . txFont) ; 

TextFace CniyTextOptions . txFace) : 

Text Size CmyTextOptlons.txSize); 

GetFontInf o (SinyFontlnfo) : 

// cakuhuc track width and height hased on text 
myTCHeight = FlxFatio(myFontlnfo.ascent + 

myFontlnfo.descent + 2, 1): 


YolFH notice that we determine the height of the timecode 
track by adding the distance from the font baseline to the 
asf'ent line and the distance from the baseline to the 


Creating a Track Reference 

The final thing we need to do, when creating a 
timecode track, is to create a track reference from the 
target track to the timecode track, like this: 

inyErr = AddTrackReference {myTypeTrack . myTrack* 

TlmeCodeHediaType, NULL): 

Listing 4 shows our complete function for creating a 
lime code track in a movie. 

Listing 4: Adding a timecode track to a QuickTime 
movie 


QTT C_ AddTi meCodeToM o vi c 


OSErr 

( 


QTTC_AddTi fiseCod eToMo vie 

(Movie theMovie, 


OSType 


Track 

Track 

Media 

MediaHandler 

TimeCadeDef 

TimeCadeRecord 

Str63 

TimeValue 

HatrixRecord 

F ixed 

Fixed 

Fixed 

long 

TCTextOptions 

Forvtinfo 


myTypeTrack = HULL: 
rayTrack ” NULL; 
myMedia = NULL: 
myHandler = NULL; 
myTCDef; 
myTGRec; 
tnyString; 
myDuration: 
myMat rix: 
inyWldth; 
myHeight: 
myTCHeight: 
myFlaga = OL: 
myTextOptlons: 
myFontlufo: 


theType) 
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TiinsCodeDescrlptionHandle myDesc = NULL; 

1 OTi g * * my Fr ameHand 1 e; 

OSErr myErr = noErr; 

if get the (first) ttack of the specified type; this track determines the width of 
the new timecode tmek 

myTypeTrack = GatMoviaIndTrackTypa(theMovla. 1, 

theType* movieTrackMediaType); 
if (myTypeTrack =™ NULL) [ 
myErr = trackNotInMovie: 
goto bail; 


// get the dimensioiis of the target track 

GetTrackDimensions (myTypeTrack» &myWidth, SimyKeight); 


// create tiie timecode track and medk 

myTrack = NewMovieTrack(theMovie* rnyWidth, 

kTime C od eT ra ckSiz e ^ kNoVoluma); 
if {myTrack = NULL) 
goto ball; 


myMedia 
0 ): 


NewTrackMedia(myTrack. TimeCodaMediaType. 

GetMov± eTime S c ale(theMovie)» NULL♦ 


if (myMedia = NULL) 
goto bail: 


myHandler = GetHediaHandler(myMedia); 
If (myHandler = NULL) 
goto ball; 


// fill in a timecode definition structure; this becomes part of the timcaxle 
description 


// set the timecode formal informatkm ftag^i 
if {gU3eTlmeCode) I 
myFlaga OL; 
if (gDropFrameVal) 

myFlags |— tcDropFrame; 
if (gIsNeg) 

myFlags j= tcNegTimesOK; 
if Cg24Hour) 

myFlags |“ tc24HourMax: 

[ else { 

myFlags = teCounter: 

1 


myTGDef*flags - myFlags: 
myTCDef^fTimeScale - gTimeScale; 
myTCDef.frameDuration = gFrameDur: 
myTCDef.numFrames ^ gNumFrames; 

// fill in a timecfxk record 
if (gUseTimeCode) [ 

myTCRec,t.hours = (UIntS)gHours: 
myTCRec,t.minutes = (UlntB)gMinutes; 
myTCRec.t.seconds - [UlntB)gSeconds: 
myTCRec.t.frames = (UlntS)gFrames: 
if (glsNeg) 

myTCRec.t.minutes |“ tctNegFlag: 

] else f 

myTCRec.c.counter = gCounterVal: 

] 


// figure out the timecode track geometry 

U get display options to calculate box heiglit 
TCGetDisplayOptlons (myHandler. &rmyTextDptions) ; 
GetFWum {gFontNatne * fiemyTextOptions. txFont) ; 
TCSetDisplayOptions(myHandler, StmyTextOptions); 

// use the starting lime to figure out the dimensions of track 
TCTimeCodeToString(myHandler, &myTCDef* imiyTCRec, 

myStrlng); 

TextFont(myTextOptions.txFont); 

TextFace(myTextOptions * txFace): 

TextSize(myTextOptions.txSize); 


Get Font Inf o(5miy Font Info) ; 

// calculate track width and heiglit based on text 
myTCHeight = FixRatio{myFontInfo.ascent + 

myFontInfo,descent +2, 1): 
SetTrackDimensions(myTrack. myWldth. myTCHeight): 

GetTrackMatrix (myTrack ^rnyMatrlx) ; 
if (gDisplayBelowVideo) 

TranslateMatrixCSimyMatrix, 0. myHeight): 

SetTrackMatrlx(myTrack. S:myMatrix) i 
SetTrackEnabled(myTrack. gOlsplayTimeCode ? true : 
false); 

TCSetTimeCodeFlagB(myHandler, gDisplayTimeCode ? 

tedfShowTimeCode : 0. tedfShowTimeCode): 

if edit the track media 

myErr = BeginMediaEdits(myMedia): 
if [myErr = noErr) i 
long mySize: 

UserData myUserData: 

// cit-'att: and ainfigure a new linicctxle description handle 
mySize = slzeof(TimeCodeUescrlptlon) ; 
myDesc “ (TimeCodeDescriptlonHandle) 

NewHandleClear(mySize): 

if (myDasc = NULL) 
goto bail: 

(**myl>esc) .descSize = raySize; 

(**myDesc) ,dataFormat = TimeCodeMediaTjrpa; 

(**myDesc).timeCodeDef ^ myTCDef; 

// set tlic souitc identification inJbrmatitjn 

// the source identificatif>n information fiir a fimcetxtc track is sttired 
// in a user data item of typeTtiStmiceKcfNamei^'pc 
myE r r “ NewU s e r Da ta (EimyUs e rDat a): 
if (myErr ^ noErr) f 

Handle myWameHandle = NULL; 

myErr “ PtrToHand(^gSrcNarae[l]. &myNameHandle, 
gSrcName[0]); 

if {myErr = noErr] [ 

myErr AddUserDataText {myUserData. 
myNameHandle * 

TCSourceRefNameType. 1. 

langEngllsh); 

if (myErr noErr) 

TCSetSourceRef(myHandler. myDesc. myUserData): 
J 

if (myNameHandle != NULL) 

DlsposeHandle(myNameHandle): 

DisposeUserData(myUserData); 

i 

if add a .sample to die timecode track 

myFrameHandle = (long '^*)NewHandle(Blzeof (long)) ; 
if [myFrameHandle = NULL) 
goto ball: 

myErr - TCTimeCodeToFrameNumber(myHandler. 

Si (* * myDesc) . timeCodeDef > fitniyTCRec > 

*myFrameHandle); 

// die data in die timecode track must be big<^nclian 
* * myF r ameHand1e = EndianS 3 2_Nt oB(* * myF r ameHand1e): 

myDuratlon = GetMovieUuration(theMovie): 

// since we created the track with the same timescaie as the movie^ 
ff we don't need to convert the duration 

myErr - AddMedlaSample(myMedia, 

(Handle)myFrameHandle, 

0* 

GetHandleSise((Handle)myFrameHandle), 
myDuratlon, 

(SampleDesc riptionHandle)myDesc, 

1 , 0 , 0 ): 

if (myErr 1= noErr) 
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goto ball: 


myErr ^ EndHediaEdits{myMedia): 
if (nryErr noErr] 
goto bail; 

myErr " IneettlyfedialGtoTrack(inyTrack. 0. 0. 

my Dtt rat ion. f ix ed 1); 

if (myErr !“ noErr) 
goto bail: 

if create a track reference the target track to the timecode track 
myErr ” AddTrackReference (myTypeTrack, myTrack, 

TimeCodeMadiaType. NULL): 


bail; 

if CmyDese 1- NULL) 

Dis po s eHand1e{(Hand1e)myDes c): 

if CmyErameKandle 1= NULL) 

DisposeHandle((Handle)myFrameHandle ); 

return(myErr): 

I 


Getting Information about a Timecode Track 

The timecode media handler provides several 
functions that we can use to get and set information about 
a timecode track in a movie. For example, if we want to 
get the current timecode value for a movie, we can call 
the TCGetCurrentTimeCode function. Listing 5 defines the 
QTTC^ShowCurrentTinneCode function, which QTTimeCode 
uses to get the current timecode value and display it in a 
dialog box to the user. 

Listing 5: Displaying the current timecode value 


QTTC_ShowCurrentTimeCode 
void QTTC_ShowCurrentTimeGode (Movie theMovie) 

I 

MediaHandler myHandler = NULL: 

HandlerError myErr = noErr; 

TLmeCodeDef myTCDef; 

Time CodeRe cord ir^TCRec: 

myHandler = QTTC_GetTimeCodeMediaHandler(theMovie); 
if [myHandler != NULL) { 

jf the timcxxjde ibr die Current riiovie time 
myErr = TCGetCtirrentTimeCode(myHandler, NULL, ScinyTCDefT 

ficmyTCRec, NULL): 

if (myErr = noErr) I 
Str255 myString: 

myErr = TCTimeCodeToString(myHandler. fitmyTCDef. 

&myTCRec. roySt ring); 

if (myErr ^ noErr) 

QTTC_ShovSt rIngToU s e r(my St rIng): 
t 


1 ] 


As you can see, QTTC_ShowCurrentTimeCode first retrieves 
the instance of the timecode media handler and then calls 
TCGetCurrentTimeCode to get the current timecode value. 
Then it passes the timecode definition structure and 
timecode record filled in by TCGetCurrentTimeCode to the 
TCTimeCodeToString function, to conven the timecode 
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value into a string. Finally, QTTC_ShowCurrentTimeCode 
calls the application function QTTC^ShowStringToUser to 
show the string to the user. 

Similarly, we can display a timecode track’s source 
information to the user by calling the 
QTTC_ShowTinneCodeSourc 0 function defined in Listing 6. 

Listing 6: Displaying the timecode source information 


QTTC_ShovvTUn(K:;0cIeSoun:c 

void QTTG_ShoWrimeCodeSource (Jlovle theMovleJ 

( 

MediaHandler myHandler = NULL; 

KandlerError myErr “ noErr; 

UserData myUaerData: 

myHandler = QTTC_GetTimeCodeMediaHandler(theNovieJ; 

If (myHandler t= NULL) I 

// get the timecodie source for the current nit me time 

myErr = TCGetCurrentTimeCode(niyHandler, NULL, NULL, 

NUll.. SdnyUserData) : 

if (myErr = noErrJ [ 

Str255 myString “ " [No source name!]'*; 

Handle myNameHandle = NewHandleClear(0); 

GetUserDataText (inyUserData ♦ myNameHandle, 

TCSour c eRefNameTyp e, 1, 1angEn glish): 
if (GetHandieSize(myNameHandle) >0) ! 

BlockMoveC‘myNameHandle, imyString[l], 

GetHandleSize(myNameHandle)); 
myString[0] - GetHandXeSize(myNameHandle); 

1 

if (myNameHandle NULL) 

DiS po s eHandle(rayNameHand1e); 

QTTC_ShowStringToUser(myString): 

DlaposeUaerDataCnyUserData): 

\ 

} 

I 

One thing to notice here is that the TCGetCurrentTimeCode 
function returns, through its last parameter, a user data list 
that contains the source information of a timecode track. 
(We didn’t need the source information in Listing 5, so 
there we pas.sed NULL for the last parameter.) Once we've 
successfully retrieved that information, we can use the 
Movie Toolbox user data function GetUserDataText to find 
the source information and then display it to the user. 

Showing and Hiding a Timecxide Track 
As we’ve seen in earlier articles, we can show or hide 
a specific track in a movie by enabling and disabling that 
track using the Movie Toolbox function SetTrackEnabied. 
For example, we can toggle the visible state of a track 
with this line of code: 

SetTrackEnabledtmyTrsck, IGetTrackEnabled (oiyTrrack)) ; 

With a timecode track, we also want to keep the 
media handler informed of the visible stale of the track by 


setting the timecode flags appropriately, like this: 

TCGetTimeCodeFlags (myHandler . 5tmyFlags) : 
myFlags tedf ShowTiraeCode: 

TCSetTimeCodeFlaga (myHandler . niyElags . 
tedfShowTimeCode); 

Ffere, we simply retrieve the current timecode flags, t€>ggle 
the tedfShowTimeCode bit, and then send the new set of flags 
back to the timecode media handler. The third parameter to 
the TGSetTimeCodeFlags function is a mask that indicates 
which bits in the myFlags parameter to consider. As you can 
see, we want the media handler to change only the 
tedfShowTimeCode bit itself. Listing 7 shows the complete 
definition of the QTTC_ToggleTimeCodeDispJay function. 

Listing 7: Toggling the visible state of a timecode 
track 


QT rC_ToggleTimeCodeDi s play 

void QTTC^ToggleTimeCodeOisplay (MoviaController theMC) 

1 

Movie myMovle = MCGetMovie{ theMC) : 

Track myTrack = MJIX; 

MediaHandler myHandler ” NULL; 

long myFlaga = OL; 

// get the (first) timeccjde track in the specified movie 
myTrack ” GetMovielndTrackType(myHqyle. 1, 

Tima CodeMe dlaTypa, movieTrackMe diaType); 
if (myTrack 1- NULL) ( 

// get Hie timecode track's media handler 

myHandler = QTTC_GetTimeCodeHedlaHandler(myMovie): 
if (myHandler 1= NULL) I 

// toggle the show-timecode fitg 

TCGetTimeCodeFlags (tnyHandler, knyFlags); 

myFlags tedfShowTimeCode; 

TCSetTiraeGodeElage (inyHandler. myFlags, 

tedf ShoirfTinieGode); 

// ttjggle the track enabled state 

SetTrackEnabied(myTrack, !GetTrackEnabled(myTrack)); 

// now tell the movie ojittniUer the movk: has changed^ 

// ao that the movie lectanjde gets uptlitcd correctly 
MCMovi eChaiiged (t heMG, myMovi e); 

I 

I 

1 


Notice that we cull MCMovieChanged to prompt die movie 
controller to reset its state based on the current prop^erties of 
the assexiated movie. This causes the movie controller to 
recalculate die controller rectangle and redraw die movie. 


Conclusion 

As we’ve seen, it’s quite easy to create and 
manipulate timecode tracks. These tracks take up very 
little space in a movie file, and they can be extremely 
useful in coordinating QuickTime movies with their 
external source material. While timecode display is 
principally useful to video or audio editors, the counter 
display can serve a variety of purposes. B 
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KOOLTOOL5 


by Xplain Staff 


Kick-Off! 

Kick-Offi LO is the football-shaped USB cousin of Rebound! 2,0, 
the remote server godsend produced by Sophisticated Circuits, 
Because of subtle differences between the USB and ADB 
communication channels, Kick-Off! requires a slighdy more 
complicated set up than Rebound. Rebound is a simple ADB device 
that plugs into your computer's ADB port and allows your keyboard 
to plug into it, thereby intercepting signals between the two, Kick- 
Off! has a slightly more complicated setup. It plugs into your 
computer's power outlet, and has your existing power cord plug into 
it, while at the same time plugging its USB cable into your 
computer’s spare USB port. Once youVe got the hardware set up, 
just run the installer and you can say goodbye to remote serv^ir 
downtime,..almc^t, 

Kick-Off!'s mast basic and helphil feature is the ability to restart 
the computer when tlie system crashes, but there are some 
qualifications that should be made. The main issue I had with Kick- 
Off was not that it failed to detea crashes and restart properly, but 
that it did it too often, sometimes when the machine had not even 
crashed! Bew^ire of applications that hog the system’s prcKessing 
abilities. For example, in my first test of Kick-Offi, I wanted to take 
tlie processor out for a little spin, so I started up Quake III and began 
blowing bots to oblivion. Although 1 had almost instandy forgotten 
ahx:>ul my Kick-OflR test, I w^ cruelly reminded w'hen the machine 
abruptly rebooted exactly one minute into my game (I had set the 
crash deteaion timer to one minute)! However, w'hen I restarted 
Quake and changed from fuU-screen mode to a w^indow, it worked 
fine, NoWj nobody in their right mind would ev^er play Quake in a 
w^indow, so if you are mnning applications like this, Kick-Off! will 
not make you happy. 

Still, most servers aren’t running applications like Quake BI, and 
it would be unfair of me to base my entire review upon this one 
aspea of Kick-Off!. In most other situations, Kick-Off! performed 
exactly as planned. Its reboot mechanism w'orks well when the 
system does in faa crash, and can be used in conjunction with 
application crashes as well, which is a particularly helpful feature if 
you are using Kick-Off! on a remote server, Kick-Off! is able to 
respond to application crashes in a variety^ of diflferenl w'ays; it can 
restart the application, or the computer, or both, or any combination 
of either, I used Crash Test, I freew^are application (also from 
Sophisticated Circuits) that causes several different types of system 
and application crashes, to test Kick-OfT!’s effertiveness. For two 
types of system crashes, Kick-Ofifi deteaed the crashes admirably 
and restarted the computer as planned. Crash Test can also perform 
two t>q>es of application crashes: it can hang an application, and it 
can allow its application timer to expire. The latter Rinction is 
designed specifically for Sophisticated Circuits' equipment, and not 
surprisingly, Kick-Off able to accurately detea this type of crash 
and relaunch die application. However, wBen I told Crash Test to 


“hang" itself, Kick-Off! understood this as a system crash and 
performed a hard restart when the system timer expired. So, while 
Kick-Offi’s system crash detection works quite well, its application 
crash detection is not quite as effective. 

1 recommend using Kick-Off! in place of Rebound on remote 
Mac servers that suppon USB (rather dran ADB) devices. However, 
it is somewhat limited in its ability^ to correctly ascertain whether a 
particular application lias crashed or not, and you will not find it 
reliable without an additional line of defense. Make sure that if you 
are using Kick-Off! to relaunch applications, you have adequately 
tested them and are sure that they support the Kick-Off! application 
timer. While KickOfR is not the savior of nemork administrators, it 
will help to reduce those 3 AM trips to the Office for server restarting. 

Sysuogd 

If you Ye like me, you w^ant to know^ as much as possible about 
what’s happening with your netw ork at all times. If you’re having 
unidentified problems and you want to see wYiat your switches are 
doing, you can be in a tough spot if youYe using a Mac. In steps 
Syslogd, a sliareware utility program written by Brian Bergstrand, 
The current version of Syslogd (2.1.8) allows an administrator to view 
all sorts of actions taking place on his/her network. 

Syslogd is, of course, titled after its UNIX namesake. 
Accordingly, it brings you right down to the nitty-gritt)' computer 
instmetions that tlie Mac OS historically prevented the user from 
seeing. How ever, for the network administrator interested in such 
matters, Syslogd serves up a hot plate of delicious, abstruse UNIX- 
style information. Easily downloaded at Beigstrand’s web site 
www.dassicalguitar.nel/brian/apps/syslogd, the application features 
a quick AppleScript installer to get you started, (You will need 
AppleSoipi installed to perform some of SyslogdY convenient 
functions, but the actual application will run without it). Make it a 
point to also dow^nload Stairw^ays’ Tnterarchy 3.8, w^hich provides you 
with some helpful tools (including a UDP Ping-er) if you get stuck 
using Syslogd, The Syslogd application should load and begin 
running on s^cstem start-up, but you’ll want to run the Syslog Console 
application as well, at least at first. In order to get information 
displayed in the console window^ 1 liad to set up a CONSOLE log in 
die Syslogd Admin control panel, which is a piece of cake. After a 
Syslogd restart, you should start seeing messages zip across die 
console window, If you choose not to use the console application, 
you can still view the logs in your favorite text-editor, after running 
the Cycle Logs AppleScript included in the package. Presumably, you 
should be able to find the information you’re looking for somewhere 
in the Syslogd logs. 

Unfortunately, Syslogd 2,1.8 will not mn on your old ICIII, or 
any other 68k machine. In addition, Syslogd is not compadble with 
Timbuktu, and you can exped a system crash if ever the twain shall 



KoolTools 


MAt/TECH • December 2000 








meet. While setting up the application and getting messages to 
appear in tlie console window was not particularly intuitive 
(especially if Interarchy is not available), Betgstrand himself Ls a 
fantastic resource if you get into trouble. 

Link Tester 2.5 

Recently, I lutd tlie opportunity to evaluate Link Tester 25 from 
VSE Software on our www.mactech.com website. Link Tester is a 
program that crawls its way through your web site following each 
link in your site oneh)y-one (it can test web pages, images, 
downlcyadable file links, ajxl even JavaScript links) and reporting any 
pages that have prc^bleins displaying or any pages that link to dead 
material on tlie World Wide Web. 

The program has a rather pleasant, if minimalistic, user 
interface and is preny straightforw'ard to use. You simply install 
the program on your machine, enter tlie w'eb address of your 
web site, and let Link Tester do all the w^ork. You may tell Link 
Tester to check just links on pages you specify, or to follo%v all 
links on your site recursively. The default mode Is to check all 
links on your site recursively. 

As a link is broken or otherwise malfunctioning it is added 
to a HTML-formatted report that is presented to you at the end 
of the site evaluating prcxess. This report lists all links that were 
checked, the broken ones, and the reasoo(s) for failure. There 
are options to save this report and you can even click on the link 
of the bad page just to see that indeed the link is really broke. 
In addition you can also click on an error message for a more 
detailed description of that message. 

Link Tester will attempt to open multiple connections to tlie 
website being tested so that it can complete its job faster. You 
are allow'ed some control over this by being able to choose a 
^Server Load' level of 5 different steps between Very^ High and 
Very Low. It is recommended that W'hen connecting to remote 
senders you sliould always use the Very Low^ setting out of 
respect to tliose server operators. 



Mac OS X 


Making the Move 


With J l trlCj )!(just over the 
Mac ilcHiopCr^ everywhere have a 
major need for GARB ON and 
application porting, user interface 

Implementation, and Hililli development 
services. Toward that end, several 
high-quality engineering 

firms, in association with the fIPPLi 


MacSense Cr-2? Cable Tester 

For mast of us, working widi computer cables is about as 
enjoyable as being a White House intern. You have to make sense 
of indistinguishable strands of gray matter, often woven together in 
im intricate pattern of loops, tangles, and knots, in order to get at 
them, you are often required to move hea\y furniture, or wedge 
yourself in unsavojy^ pLices iliat even tlie vacuum cleaner lias 
forsaken. All too often, aU of your enetgy goes for naught when you 
later discover tliat you put a bad cable in place. For anyone who 
know's tills frustration, the MacSense Cable Tester is for you. 

Tlie CT-2 is a simple, yet ingenioUuSly de.signed device that 
will save you hours of troubleshooting agony. It has six main 
ports: tw'o each of RJ-45 (Ethernet), RJ-11 (telephone), and 
MiniDin (serid), Plug each end of a cable into a port, pres.s a 
button, and the CT-2 w ill tell you which pins or wires within the 
cable are responding, and how^ well. It can also tell you whether 
the connection is parallel or non-parallel Never again will you 
confuse a crossover cable and a patch cable, nor will you waste 
time installing a cable that doesn't work, or doesn't w^ork well. For 
older networks, the CT-2 has a BNC port that can accommodate 
a lObaseZ T-conneaor and determine its tenninator value. 


CEUQOPQl CONNECliON, are offering these 
services at very aiiraolwe discounts 
to all Select and Premier members. 


The following pages 
are those vendors that 
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Get the power and experience you need from 


PROSOFT 


engineering,inc. 



With over thirteen years in providing 
programming service to the Mac cornmiini^f^! 
Prosoft is committed in delivering the ultintdte 
quality software products and service. 


Our Engineers have extensive knowledge in; 


Macintosh PPC Drivers, 
Shims and Extensions 

Macintosh Power Plant 
Applications, Mac OS X 
applications and drivers 

Carbon application 
porting for Mac OS X 

Multimedia and QuickTime 
Applications 

Unix/Linux Console 
Applications, including 
Unix Solaris, xBSD Drivers, 
and Linux Drivers 


o 

• Windows 95, 98 

0 

• Window CE 

a 

• Windows NT, 2000 

3 

o 

(A 

• Unix / Linux 

0 

• Java 

(D 

X 

TB 

• Embedded OS 

(D 

• RDBMS 

(A 

(D 

• Network Consulting 


WWW. prosoffeng .com 


tel: (925) 42 6-6 100 


sales@prosofteng.co 











Don't want to miss the mark while moving to Mac OS X. Come to RecoSoft. We're the experts in developing software 
for the Macintosh platform. Our quiver of skills rnciude Macintosh Application Design & Development. Cross Platform 
(Mac/Win/Linux) Development Services, Double Byte and Localization Solutions, Software Quality Assurance & 
Contract Programming Services. We've also hit bulls eye in AQUA implementation, CARBON porting, QuickTime development 
and Japanese Language implementations. So, if your aim is to get 

the best software development for Mac OS X, target the experts. ^ RECOSOFT CORPORATION 




Recosoft Corporation, Osaka, Japan. Tel.: +81'6-6443-001 5 Fax: +81-6-6443-1458 E-mail: Enfo@recosoft.com Website:www.recosoft.com 







“We have found the engi¬ 
neers at Art & Logic to be 
outstanding—better than 
excellent. When we use 
their software development 
services, we get results.” 


Art & Logic, Inc. 

www.artlogic.com 
877-278-5644 {toll free) 
info@artlogic.com 


The software engineering company that helps bring your 
hardware product to market—guaranteed. 


Since 1991, high tech companies tike Apple Computer, 
Hewlett Packard, and Leica Microscopy have turned to 
Art & Logic for assistance in implementing cutting 
edge technologies. 


Now, with the advent of OS X, Art & Logic is helping 
companies make their products compatible with 
Apple’s new operating system. Art & Logic engineers 
are industry leaders in Carbon & Cocoa porting. Aqua 
implementation, and driver development. 


in the new economy, where time to market is every 
thing, you need results. Art & Logic delivers. 












Software Development 
>utsourcinq Since 1990 




415.491.2200 

www.shadetreeinc.com 







Red Rock Software specializes in the Macintosh software devel 
opment. Red Rock Software's team of senior engineers aver¬ 
ages over 10 years of development experience on the 
Macintosh platform. Our expertise and experience has gained 
us the trust of companies like Apple Computer, Iomega 
Corporation and Sorenson Media. 


If you are looking to get your product compatible with Mac 
OS X quickly and with extreme quality, let our experts help. 

• Aqua Interface Implementation 

• OS X Carbon Porting 

• OS X Native Cocoa Application Development 


call Red Rock at 888.689.3038 
or visit us online at www.redrocksw.c 


□ Eat your vegetables. 

□ Exercise every day. 

^ Port to Mac OS X. 

□ Call your mom. 

All of these are good for you. 
We can make one of them easy. 


since 1969, The Omni Group has worked with the technologies that have been reAned Into Mac OS X. 

Moving ID Mac OS X te a Mg step for your company, and you need consultants who can help you both 
plan how best to make the transition and follow whatever path you choose. 

That's been our business for years. No matter what kind of product you have, we can get it up under 
OS X. fast: 

• Real games: We ported id's Doom and Chiake games to NEXTSTEP and OS X. Q]iake 2 took us a week. 

• apps: We ported Adobe's ErameMaker to NEXTSTU* and Sun's Concurroice to OpenStep/SoIaris. 

• Big libraries: We ported the Oracle 8 client libraries which /^ple ships today in OS X Server. 

• Sa^us drivers: We ported Sdfx's Glide and wrote Voodoo2 and Rendition drivers for OS X Server. 

We've written new mouse drivers for OS X Server and joystick drivers for OpenStep. 

• New apps: We wrote OmnlWeb, the only native OS X web browser, and OmniPDF, the native Acrobat 

viewer for OS X. 

Mac OS X Is what we do. Let us help you do It, too. 



Group 



2707 Northeast Blakeley Street 
Seattle. Washington 98105-3118 
www.omnigroup.com/consultlng 


saies@omnigroup.com 


800.315.0MNI x201 
206.523.4152 x201 
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Robosoff has grown lo be one of the most experienced Mac product 
development outsourcing companies. Here ore a tew reasons why.. 


u 


Robosoffs be.^t of class development practices help them deliver the impossible - 
high quality solutions, on budget, on time. 

They are one of the finest Mac developers we have in Asia and 
Apple is proud to be their partners in progress. 




Eshwar Vangala, App^e Computers. 


u 

Rohosofi completely rewrote my software application 
exceeding my every expectation. In terms of 
attention to technical detail and understanding 
the business issues of the NetJumper product, 
the Rohosofi team were exceptional 

Gilbert Borman. NetJuniper Inc 



\fter working with Rohosofi on Mac VersaBook 
project, we have no doubts that we will want 
to continue working with them in the future. 
Their attitude was a/ways positive and did 
anything that we needed to help us get 
the product released. 

Jake Benjamin, Versaware Technologies. 


robosoftin.com 


a 


Rohosofi Technologies receives my ve^y highest recommendation. Prior to 
awarding Robosoft my current ASP project, / had never met the staff and had 
great concerns about distance and communications. My worries turned out to 
be unfounded, Robosoft could not have been more responsive if they were in 
the next office. Alt hough ! have yet to meet them personally, i think of 
Robosoft, not as a contractor, but as my IT partner. 


n 


Barry Shapiro, The Anderson Group. 


Partners 
in Product 
Development 


info@robosoftiri.com 

+91>82S2>35458 








lliere are many aible testers on the market, but die CT-2 has 
one essential advantage: it splits into mo pieces, allowing you to 
test cables whose ends are no where near one anodien 
Additionally, the CT-2 can test LX)rinections thnjugli other devices. 
For example. I recently used tlie CT-Z to debug a pniblem I was 
having insuiDing a new Ethernet jack in the wall. Through repealed 
uses of the CT-2, I was able to quickly isolate the pniblem, which 
turned out to t^e a faulty Etliernet port in cjne of our hubs! At one 
point r had one end of the CT-2 ctrnnected lo one end of a patch 
cable, which expected to tlie patch panel, which connected to 
Category 5 wire running tliiough the walls to the jack that I had just 
installed, to which another patch cable wa.s connected, on whose 
other end the remainder of the CT-2 rested. Clearly, without the CT- 
2 I w^Quld have been helpless. 

MacSense lias just released a new^ and improved version of the 
Cr-2, known as the CT-210, which sivaps the older serial ports for 
LfSB ports. Tlie essential functioning of the device remains the same. 
If you ever have to do nemork troubleshooting, save yourself a lot 
of frustration and pick up a CT-210 cable tester from 
www.devdepot.com. 

Cleaners 

If you spend any time at all working with multimedia 
files, Terran Interactive's latest release of Cleaner will quickly 
become one of your favorite applications. Especially useful for 
creating streaming multimedia files, Cleaner is a powerful 
program tliat can be equally appreciated by the high-end 
system administrator for making streaming QuickTime or 
RealSystem movies, or by the enterprising college student 
ripping MP3s in the wake of the Napster fallout 

As you can see from the list of supported file types below, 
Cleaner is about as versatile as they come. In addition to 
merely converting these files, Cleaner gives you the ability to 
tack on a few bells and whistles as well, such as adding fade 
in/fade out to audio or movie files, or blurring/sharpening 
image files. Aside from out and out editing of the actual 
content of a file. Cleaner is a fully functional application for 
putting the finishing touches on any media project. 


DV 

Reads 

Writes 

QuickTime 

Reads 

Wriles 

WAV 

Reatk 

Writes 

PICTJPEG, PNG, BMl^ 

Reads 

Writes 

OFF, GIF 

Reads 

- 

RealSystem 

- 

Writes 

Windtsw,s 

- 

Writes 

Video for (AVI) 

Reads 

Writes 

MPEG-l 

Reads 

Writes 

MPEG-2 

Reads 

Writes 

MPEG Layer I and n audio 

Reads 

Writes 

OpenDML 

Reads 

- 

Macromedia Flash 

Reads 

- 

IVIP3 

Reads 

Writes 

AIFF 

Reads (including 
importing audio fiom 

CDs on Mac ) 

Writes 
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Stay suited up with The Regulator Pro^'^ UPS 
for Macintosh® Computers from Belkin. 

The Coast Guard calls it Semper Paratus—always 
prepared. To us, it's the Regulator Pro Gold Series. 
Belkin knows you can't afford to risk your data and 
hardware to unpredictable forces like blackouts, 
brownouts, spikes, and surges. With a Data 
Recovery Warranty, a Connected Equipment 
Warranty, and up to 45 minutes of battery back-up 
time, as well as the great features listed below, 
we're here to make sure you won't 
get caught with your.,, uh, guard down. 


• Powerful 500VA and 650VA models available 

• Automatic Voltage Regulation (AVR) 

• Ships with free shutdown management software 

• Compatible with PC or Mac® OS 9.0.4 and higher 

• 8 AC outlets 



beHtln.com 


Belkin Components - 310.898.1100 * Fax 310.898.1111 
Compton, CA • Atlanta, GA - United Kingdom • Holland 

Atl right& reserved, AH trade naines are registered trademarks of respective manufacturers listed. 
Selkin CompoiientB. 20AD3S8 






























Coming to a MacTech 
near you... 


ADC Direct 

A regular update from the 
Apple Developer Connection 


Apple Developer Connection will bring you regular updates on technical 
issues, resources available, and insights from those in the know at Apple about 
the best ways for developers to work with Apple, and take advantage of what 
they have to offer. This new section will be featured in every issue of MacTech, 
starting with January, 2001! 


Catch the maiden voyage of this new section in the January, 2001 issue! 


A Die 


Apple Developer Connection 








Share your high-speed Internet connection and 
protect your data from unauthorized access with the 

N etLI N E~ Broadband Gateway 




The NetllNE 


m for 

yjonie, office or school! 


Broadband Gateway 

allows you to share a high-speed Internet 
connection, such as Cable or DSL, with 
multiple computers using just a single IP 
address from your ISP. 

The built-in firewall wDl protect your 
important files by preventing unauthorized 
access via the Internet, 

Works with both Macs and PCs. Web- 
based configuration makes set-up a breeze. 

Receive a coupon for 
25% off a Farallon hub 
or switch when you 
purchase the NetLINE 
Broadband Gateway, rt/sonw 

For more information contact 
Dr. Farallon at 1 -800-613-4954 or 
visit us on the web at www.farallon.com 



Internet 

Connection 



Cable4>$L 

Modem 




Ihz NetLINE Broadband Gateway connects between 
your network and your Cable/DSL modem 


!#EP0T. 
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□ OT. Serve. Run. Run. Run ... 


One Imiimilon tiiat I mn into when using Cleciner tjccurred when I 
tried to bum an Audio CD of AIFF files exported from Cleaner using 
Adaptec Toast. The AIFF files expc)ited by Cleaner were 
compressed, and Toast didnt want to bum tliem. I quickly found a 
simple work-around, however, by using SoundApp (a tiny 
sliareware application) to convert Cleaners AIFF files to SoundApp's 
AEFF files, which Toast happih" accepted. (Note that SoundApp 
alone is not a viable solution, since it only reads WAVs, ATFFs, and 
Miic S^^tem Sound files.) Unfortunately, Cleaner also won’t read 
RealAudio d(xumenLs, so converting all those Grateful Dead shows 
y(;u downloaded from ftp://ftp.deadshow.conV to .MP3 won't work 
either. T know, I know...it hurts me too. 



INTRQPui:?{Ni3 Champion Server 1-2,1 


Figure L Cleaner 5 eats ht il ain t read RealAudio. 


.Still, Cleaner 5s batch pixx:essing capiidty makes it a must if 
you are working with laige numbers of files, and its easy to use 
interface makes chcxrsing foni its inynad options surprisingly easy. 
One additional feature that 1 did not gel to try oitf is MotoDV, wiiich 
allows you to capaire DV directly from your FireWire compliant 
video camera. Terran promotes Cleaner 5 as a '^complete camenHo 
web" solution, which 1 don’t see how tiiey am ji^stify when you 
consider Cleaner’s inability to actually edit die content of movies (a 
la Final Cut Pro or iMo%de). However, its Leathennan-like aliilities 
mean tliat if you ftiven’t already, you will gready benefit from 
abiding Cleaner 5 to your multimedia appliaition arsenal. El 
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Saipting Saves Time - InstallerMaker 
provides full scriptability for all features. 
Automating the build process saves time 
and helps ensure the integrity of your installer. 


Tnalware in Minutes - Creating trial ware is a 
breeze with InscallerMaker. With just a few > 
clicks, and no extra coding, you can create ^ 
trialware that is e-cotnmerce ready. 


Update in a Flash - Easily build intelligent ^ 
"diff" files in installers to create small updaters for quick 
online distribution. From one simple installer; you can 
update f>Sk, PowerPC or FAT applications. 


More Details Online - There’s a lot more 
InstallerMaker can do for you. Get all the 
info at v^nvw.aladdinsysxom. 


Aladdin 
i Systems 


G IlXHf AImUIiL SyjnMTB. |[K.Sluff]ThllC]ArMilk?T't$^n:Mli;[Twk,it AtjJJijiVrtlKiTB, l[^. iMta-[‘Vt'diCKIS ME IRldniHHftf itf(twr [EtpnTiw |tLik&:n. 


• Custom 
. Destmations 


• Easy 
:■ Trialware 
'■ Creation 


• Electronic / 
Transaction 
Processing 


Install or 
Uninstall 


Gitf II Together 
With InstallerMaker 


• Installation 
/romFTPor 
HTTP Sites 


When Time Is Money^ Cet It Done Fast! 

Biiild Smaller Installers-Wnh StulTli InsrallcrMakci; you'll build installers 
faster than ever before! Cxmipress ytuir installers nil average of 15% smaller 
using the power of the SvLifflt Engine . Smaller insrallevs download fastca; 
provide added space on Cd)s and servers, anti iticrease network bandwidth. 


• Resource 

Installatron 


Qukkly Clreate Demoufare Easily turn your applieatioji into a polished 
demo. Just set tlie number of days for the <.leim> to he active, paste in the 
graphics, and you're donef 


Built-In 
Resource . 
Gornpression 


Archive Freshening - Automatically update ytnir installer proiecr Hie 
eliminate repeated searches lor rnodiHed files. 


• Marketing 
vO^Q'irtumties 
ttr:His;l p You 
M^e^oney 


Shrinkwrap 
Disk Image 
Support 


Built-In 


• Hierarchical 





MAC OS X 


By Andrew C. Stone 


What A Drag! 


Creating drag wells in Cocoa 


The richness of the user interface in Macintosh OS 
X is due, in part, to the abundance of elements that 
allow dragging and dropping of data within and 
between applications. For example, Cocoa uses drag 
and drop lor applying color swatches to text selections 
and objects. Stone Designts flagship application, 
Create™, makes heavy use <)f the drag and drop 
metaphor A library of resource.s al]t>ws users to drag in 
components, pages, effects, blends, images, and 
patterns. The user can quickly .save a selection of 
graphics to one of many image formats with Create’s 
“Image Welff IT is article w ill cover the basSics of 
creating a custom control which a 1 low's a user to drag 
in a file, and then allows the user to drag out the file. 



Create*s image well (elsyou drag oiU 
data iti varifyus image formats. 


First, a bit of article administrivia. Mac OS X has 
been a fa.st moving target with the various developer 
releases, Public Beta, and soon OS X GM (for Golden 
Master which always reminds me of that Eddy Murphy 
movie about G)! Because of the changes introduced with 
each release and the several month lag time between 
penning articles and when MacTech hits the stands, 
there are times when what Eve written doesn't jive with 
the current reality. To address this, Eve added a section 
to tlie Stone Design website for MacTech article updates 
and errata. So if you gel confused, check out 
w^w^w',stone.com/dev/MacTech_Errata/ to see if there are 
updates, and if not, email me so 1 can post fixes. 

It’s actually f.|Liite simple in create new types of 
user interface controls using Cocoa because of the well 
designed hierarchy of classes that comprise the 
Application fraiiiew'ork. Your first job is to find an 
existing class that your control can inherit from, which 
will reduce the amount of code that you have to write. 
1 k eep / Deve k) p e r/Dt) c u m e n ta ti on/Coc o a / cocoa. h t m 1 
open so I can quickly navigate to the AppKit or 
Foundation APEs, But an even easier way to look at the 
object hierarchy is U) use InterfaceBuilder. First launch 
ProjectBuilder and create a new^ Cocoa Application 
project named ImageWellTester. Click on the 
“Resciurces" triangle in the Files and Groups outline 
view, and douhle-ciick the MainMenu.nib, This wall 
launch IncerfaceBuilder 

Click on the “Classes" tab of the document window, 
and then explore the NSObject cjulline view: 


Andrew Stone <Lmdrew@stone.com> washes windows at Stone Design Corp <http;//www.stone. coiti/> and divides his time between 
WTiting applications for Mac OS X and raising farm animals, including children. 
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^ Instances Classes ^ Ini^Ages ^ Sounds ^ 





NSMenuUem 

’) 


-1 

▼ NSRespoF^der 

1 AS 



NSAppFiciition 

lO 

13 0 


NS Drawer 

«o 

20 


▼ NSView 

im 

lO 

^ \ 

NSSox 

an 

20 


NSClipView 

40 

ao 


Y NSControl 

lO 

ro 

^ * 

^ NSerowsef 

40 
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▼ 

SO 

so 


NSPopUpStiUOn 

30 

so 


NSColorWell 

le 

so 


NS image View 

30 
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Interface Bu ilder lets you explore the hierarchy of 
obrjects €)ffered by Cocoa. 



wttti naiD IvaiUfsSiiriAtaH 


For professionals and novices 
Webmasters and solution providers 

No matter what your experieneet 
Scripter makes it easier! 


Our drag well is definitely a subciass of NSView, 
but we can gain further functionality by subclassing 
NSControl, which gives us the target/action support. 
Select NSControl in the Classes pane. If you hold down 
the CONTROL key while clicking on NSControh a 
context-sensitive menu appears. Do this and select 
Subclass”. A new class which inherits from NSControl 
is created and named, by default. My Control Rename 
the class to Drag Well. 

Why write code if you can have it written for you? 
You can use Tnterfacelkiilder to produce stub files 
where all you have to do is fill in the ftmctionality in 
the stubbed out methods. Click on the “outlet” icon to 
add instance variables to the class, and the icon to 
add actions to the class. For ncjw, we don't have any 
to add. Be sure Drag Well is .selected, and choose select 
“Create Files...” from the Clas.se.s menu Cor again using 
the context menu via CONTROL key). They will be 
named DragWelLm and DragWell.h - leave the “Insert 
into Project Builder” selected and click OK. 

Drag out a “Custom View" from the IB palette 
w'indow, second tab, onto to the main window. 
Choose TooLs->lnspector->Custom Class popup button, 
and click on “DragWell”. The custom view' should now^ 
say “DragWell”. Save the file. 

Go back to ProjectBuilder, select the newly added 
DragWell.h and DragWell.m and you1l see the stub: 

#import <Cocoa/Cocoa.h> 

©interface DragWell : NSControl 
I 

) 


0end 
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BEGINNER AT SCRIPTING? 

• Unique command-builders help you learn to 
assemble commands 

• Built-in tools for experimenting 

• Shortcuts to speed scripting 

EXPERIENCED WITH APPLESCRIPT? 

• Unmatched single-step interactive debugging 

• Watch and modify global and local variables 
while stepping 

• Debug messages sent to script applications 

• Includes ScriptBase to integrate scripting scenarios 


ScH(>terreceivedMocWeek's S-diamond rating-- Twice? 
"Scripter's virtuoso disf^fay of Af>pieScript/ngsovvy ond 
def^tigging wizardry make it tke l>est environment we've 
found for ieoming or creoting AppieScKpt scripts." 
^ocWeek 


Nails Agpiiitwlpt and imup 

aBBlImtttoiia wav k fa» vaul 



Main Event 
PO Box 21470 
Washington, DC 20009 
Tel: 202-298-9595 
Sales: 800-616-8320 
info®maineventcoin 
www,maineventcom 































Macworld 

Conference & Expo 



Moscone Convention Center 

San Francisco, CA 

January 9 -12,2001 



Register Online 

www.macworUexpo.com 

'M 1-800-B45-EXP0 

Refer to Priority Code: A-MTCH 















World-Class Expositioa! 

Macworld Conference & Expo/ 

San Francisco 2001 is a 
One’Slep’Sbop offering discounts 
not found anywhere else! 

• Featuring more than 500 
exhibiting companies 

• Thousands of new products, 
software and services 

• Hands-on demonstrations 

• Test-drive new technologies 

• Awards and competitions 

• Prizes, drawings, giveaways 

Special Interest 
Boulevard 

Macworld Conference & Expo offers 
so much for every Mac user! 

Check out the Special Interest 
Boulevard while you are exploring the 
exhibit floor to find and compare hot 
new products tor your particular needs. 
Popular areas include: 

• Digital Media 


Join your friends 

and coiieagues in the Mac community 
at The Largest IT event 
on the West Coast! 


Cutting-Edge 
Educational Programs! 

Conference sessions for the 
Hew, Beginning, Intermediate and 
Advanced users! 

Mecmiffttnv features technically in-depth 
presentations and issues-oriented discus¬ 
sions about professional applications of 
Macintosh technology. The Pro conference 
offers the most sophisticated training 
available on Mac networking, digital video, 
art director/creative management practices, 
and Mac systems administrations for 
large organizations. 

Macwarid/Usets continues to be one of 
the best educational values anywhere. 

The Users conference features industry 
experts offering skill development on 
the most popular Mac-related tools and 
professional development courses 
for users who rely on Apple technology 
to gain a competitive advantage. 



• Small Business 

• Sci-Tech 

• Education/Assistive Technology 

• 3D 

■ Edutainment 

Be sure to wsit www.macworldexpo.com 
for exciting additions! 


MaidBmilmrings- San Francisco debut! 

After great success this July in New York, 
MacBeginnings will make it's debut 
in San Francisco! These high-energy, 
informative sessions will provide 
first-time attendees, new and beginning 
Mac users a starting point to enter 
the Mac community. MacBeginnings are 
free and open to ML registered Macworld 
Conference & Expo attendees! 




Macworlil 

ConfarencB S Expo. 

www.SBanamfMaipo.ooin 






/^import "DragWell.h" 

©impleinentation DragWell 
@end 

Every ciLsiom view must define its own drawing 
melhod, drawRect:, where the actual drawing of the 
view lakes place. We'll want a simple, depressed 
bezeled look, with an icon to drag in the center. And 
our conlrnl will adhere to two protocols 
NSDraggingDeslination and NSDraggingSource, to 
allow both dragging out of info and accepting dragged 
in info. A complete list of the methods required by the 
protocols are found in: 

/System/Library/Frameworks/AppKitdramework/Headers/NSDragging.h 

Here's the 'well’ commented code for the DragWell 
type it in Cor download it from 
w ww.stone.com/dev/MacTech/Jan-2001/), You can 
copy and paste it as a template for use in other objects, 
modifying wliere needed to copy other data types to 
the drag pasteboard as needed. 

DrjgWcJl.h ++++++++-•-++■♦- 

#import <Cocoa/Cocoa,h> 




MTA RECOVERY: 





“Their incredibly hind staff focus on getting the 
job done as well as their customer's feelings. 
All experiences should be so pleasant. 


-Neil Hcktin, Publisher 


7 Good Reasons to Choose DriveSavers 



We Can Save W” 


INR; 415-382-2000 

WWW, d ri vesQ vers, com 


1. Fasiesi, most successful data recover)' 
service available, 

2. Retneve recovered data instantly with 
DATAEXPRESS™ erver high speed 
secuird Iniemei lines, 

3. Authorized to perform Data Recovery 
on all Apple computeis and hard drives. 

4. 24-hour, onsite, and weekend sen'ices. 

5. Advanced, proprietary im>very techniques. 

6. Featured by CNN, _ 

BBC, Forbe. Also 
in Mac World, 

Mac Addict, 

Popular Mechanics, 
and snany others. 

7. Federal and State 
Contracts 

(GSA, CMAS). Sincf 1905 



DriveSavers - Your Dato Recovery Solution! 




©interface DragWell ; NSCoiitrol 

t 

NSlmage * image; // the image displayed and dragged by 

ihe user 

NSString *file : // the fdc path that the user will drag out 

unsigned int last; // for optimising the dragging!Jpdated: 
method 
1 

// if you want to programmatically set a file in tlie well: 

' (void)setFile:(NSString *)nevFile; 

@end 

-H-H-H-I-+-H-+ DragWetl.m ++-H-+-»-H-+-«-i-n-+++ 

#import ‘’DragWell 

/* Example source by Andrew^ Stone andTew^^stone.com 
\^Tvw. stone.com for MaclVch V 

©imp lenient at Ian DragWell 

// when our DragWell is tx-con.siiiuLed from tlie nib file, awakeFromNib 
geLs called 

(voidl awakeFromNib 

I 

// this is where you register for various types of drag pasteboards: 
[self registerForDraggedTypes;[NSArray 
arrayWithObject :NSFilenainesPhDardType] ] : 


// Never add an ivar which alkicates memory withoui releasing it in 
dcalloc: 

// Don't Litter! 

{vold}dealloc I 
[file release ]; 

[Image release]t 
[super dealloc]; 

I 

// Every custom view^ must implement drawRcct: 

If Well draw our depressed hc/eled reel 

// and if thcR' is a file, we ll draw an image ftir dragging out 

(void)drawRect:(NSRect)rects 

[ 

// one simple call draws the depressed l>ejfiel: 

NSDrawGrayBeael([self bounds] . [self bounds]}: 

// if you like the pinstripes, then include diese two lines: 
[[NSColor vlndavBackgroundColorJ set]: 
HSReGtFlllCNSInsetRect([Belf bounds],3.0.3.0)); 

if find the center of the view and draw the image over: 
if (image f= nil) f 
NSPoint p: 

NSSlze sz = [Image size]: 
p.x = ([self bounds],size.width - 
az,width)/2.: 

p*y = ([self bounds],size.height - 
sz.height)/2 .i 

[image campositeToPointrp 
operation ^NSCompositeSourceOver]: 

I 

) 


ff When we set the flic, we also set the image which wc get from the 
NSWcirkspace: 

- (void)setFiler(NSString •JnewFile ( 

//it's gCHKl practice to not do anv work If notliing would change: 
if (i[newFile iaEqualToString:flie]) 1 

// live clean and let ytjur works l>e seen: 

[file release]: 

[image release]: 

ff copy the newFile into tmr instance variable file: 

file = [newFlle copyWithZoiie: [self zone]]: 
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// check If the file is nil or empty string: 

If [ Ifile II [file isEqualToString:®'"”]) I 
image = nil; 

I else [ 

if we liave a file, now let's find the image for that file: 

image = [ [[NSWorkspace sharedWorkspace] 
IcanForFlle:flie]retain]: 

J 

// we’ll need to redraw next event 

// this is the approved Cocoa way of setting ourselves “dirty” 

[self setNeedsDlsplaylnRect[self bounds] ] : 

J 

f 

// here we copy the filename to the pasteboard 

// E like to factc:ir this out because it may vary from object to object: 

- CBOOL)copyDataTo:pboard 
I 

if (file nil ([file isEqualToSt r ing : ) 

I 

[pboard declareTypes:[NSArray 
arrayWithObject^NSFllenamesPboardType] owner:self]: 

[pboard setPropertyList: [fiSArray 
arrayWithObjoct^file] forType:NSFilenamesPboardType]: 
return YES; 

] else return NO: 

f 

// DlUGGlNt; SOURCE PROltXXJL MEi'HODS 

//To add drag away functionality^ to a control, implement these: 

// draggingSourccCyperaLionMaskForLocal lets you control the behavior 
of what should 

// happen with the data on the pasteboard: copy link or any 

// the islxical flag tells you whether Uie object querying is from within 

your app 

// or from another application running on the system 


(unsigned 

int)draggingSaurceOperationMaskForLocal:(EOOL)isLocal 
[ 

if (isLocal) return NSDragOperationCopy; 
return 

NSDragOperationCopy|NSDragOperationGeneric|NSDragOperati 
onLink: 

j 

// 'fhe simple dragl mage :at: offset; event: pasteboard: source: slide back: 
method 

// is all wc do to initiate and run the actual drag sequence 

// But we only do this if we have an image and we successfully write 

our data 

// to the pasteboard in copyDataTo: method 

- (void) niouseE own : (NSEvent *)g 

{ 

NSPoint location: 

NSSize size: 

NS Pasteboard ’"pb = [NSPasteboard 
pasteboardWlthName:(NSString *) NSDragPboard]: 

if (image Stk [self copyDataTo: pb]) I 
size = [image size]: 

location.X = ([self hounds].size.width - 
size,width)/2: 

location.y = ([self bounds]* size.height - 
size.height)/2; 

[self draglmage;lmage at;location 
offset:NSZeroS±ze event;(NSEvent *)e pasteboard;pb 
source:self slideBacktYES]: 


// DRAGGINC; DRSTINATION l^ROT(lfX>l, Mpri HODS 

//To add drag acceptance functionality xo a controh implement these 

methods: 

















// this is calletl when the drag enters oiir view 
// by rettirniiig NSDragOpemtionCopy 

- (unsigned int) draggingEntered:sender 

! 

NSPasteboard *pbDard: 

last = NSDragOperatioriNone: 

pboard - [sender draggingPasteboard] ; 

// we don’t acept drags if we are the providerf! 

if ([sender draggingSource] = self] return 
NSDragOperatlonISSone: 

If ( [ [pboard types] 

nontainsObjecT;NSFllenamesPhoardType]) I 
if (image = nil) f 

image = [ [[NSWorkspace sharedWorkspace] 
iconForFile: [[pboard 

propertyListForType:NSFil©namesPboardType]objectAtIndexr 
0] ] retain] : 

[self setNeedsDisplayInRect: [self 

bounds]]: 

] 

// we'll copy or Mnk depctidiiig im the intent tif the dragging ,soutCe; 
last — [sender draggingSourceOperatlonMask] ; 

1 

return last: 

) 

// instead of constantly rccliecking the piLStchoard its Lite mouse moves 
inside the view 

// we'll simply return the eadied value that we set in liest'in 
t! raggi ngEnterccL 

- (unsigned int) draggingUpdatedisender 

return last: 



1-88-USB USB US 

-or- (1-888-728-7287) 

Worldwide Distributors of USB 
and FireWire Parts, 
Peripherals and Accessories 

Hey Developers: 

http;//WWW.usbstuC f.com/deve Lopttrs.htmt 


1-877-4 HOTWIRe 

-or- 1-877-446-8947 

fCreWCreStuff 


// Because we’re providing feedback by setting the file right wdien the 
u&CT enters 

// we’ll need tt> undt> that work if the user does not let go of the drag 
inside and exits instead: 

- (void) draggingExited;sender 
I 

// the user has exited -> clean up: 

if ([sender draggingSource] != self) I 
if (file = nil) [ 

// then unset the file image we set in mouse Entered as 
feedback.. 

[image release]: 
image ^ nil: 

[self setNeedsDisplayInRect;[self 

bounds]]: 

\ 

last = NSDragOperationNone: 

) 


// any dragging clean up miglit be done here 
// don’t foiget to return YESl 

- (BOOL) prepareForDragOperation:sender 
I 

return YES: 


//Actually do the work in this method If it's n<jt too lime consuming 
if Otherwise, you may consider returning YES, and tloing the work 
if in eonehitleOnigOperarion to prevent tht: drag from sliding back 
if hecaiisit it "timed out'’ 

- (BOOL) perfomiDragOperation: (id 
<NSDraggingInfo>)sender 
! 

WSPasteboard ‘pboard: 

pboard = [sender draggirigPasteboard] : 

[self setFile:[[pboard 

propernyLlstForType:NSPilenamesFboardType]obj ectAtlnd 
ex: 0 ] ] : 

return YES; 


- (void)concludeDragOperation;(id 
<NSDraggingInfo>)sender 
I 

if we already did the work in draggingEiitered 

//Yoti might n<uif> some titht r object that the file is here 


// this is good if you want to be able to dntg our data even if the 
window is not 

if fmnt most, the first click will do more titan just bring the window to 
front ’ 

if It will als<} allow the drag to begin on that first mcHise down 

- (BOODacceptsFirstMouse r (NSEvent *)th©Event [ 
return YES; 


@end 


Conclusion 

Adding drag tind drop support to controls and 
views is very' easy in Cocoa, Because ease of use and 
intuitive bcliavior is the keystone of Mac OS X, be sure 
to make your applications conform to this model. 

m 
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You’ll be stuck in 
San Francisco’s heaviest 
traffic and loving every 
minute of it. 


At Macworld Expo SF 2001, we make it easier for all techies, novice and expert, to have a 
space as special as their ideas. Formerly Developer Central and Net Innovators, MacTech® 
Magazine presents MacTechwi., Central—an exhibit at Macworld that showases technical 
and developer tool/service companies for the Macintosh in the biggest possible \ray. 
Macwtrld takes place in San Francisco, January 942,2001. Check out the exliibits at the 
show (Booth 3240) and on the web at: www.mactechcentralcom. 



MacTecb wt a imdenutrk ofXpfuin Corporation. MacTecb Centt^l is a sendee mark of XpMn Crjrporatiim. 

Other trudentufks and vopyrigbts appearing in this printing mmain the Imyperty of their respeeth'e holders. 



by Jeff elites <onlme@mactech.com> 


The New Basics 


Mac user out there doesn’t rememlier Apple’s famous 
1984 commercial? It only aired once, during tlie 1984 Super Bowl, 
hut it won numerous awards and is held by some to he tlie gimtest 
commercial of all times. It was directed hy Ridley Scott, director of 
Blade Rumier and more recently Gladkiton I still get cliilLs every 
time 1 see it. Hie interesting tiling to rememlx.T is tliat wlien tliat 
commercial came out, Big Brotlier was IBM — they were the 
competition, the bad guys, the emmy. Now, the villain might he 
Micrasoft (if anyone), and IBM is, well, just diere. They seem like 
neitlier enemy nor ally, just more of a quiet neighlxir — you know 
tliey're around, hut youTe not sure wliat tliey do^ TlieyVe reinvented 
tlieniselves, and there's almtjst no overlap Ix^tween their target 
market and Apple’s. Hut the landscape of computing is changing, 
and tliere’s a party going on. Ws more of a l^ave than a paity, actually 
— there's all kinds of strange smff brewing, and lot of people arc 
going hut nobody's really talking aliout it during tlie day. llie tlieme 
of the part}' is LInix, in a way, hut it’s more tlian tliat. Suddenly, Unix 
underlies every important opemting system otit tliere — except 
Window's. It’s tlie basis of Mac OS X, Liniix, liSD, and all of the 
heavyw'eight server software hy IBM, Sun, SGI, and IIP, and even 
smaller niche OSes like QNX Neutrint>. Tliis doesni mean tliat we 
are all going to band togetlier to fight Microsoft, hec'ause the new' 
W'orld isn’t alx)ut fighting with Microsoft. It isn't alxiut something .so 
negative. Tlie real point is tlial there’s an inciedihle landscape wide 
o|xm for the cross pollination of technologies, and this exchange 
isn't dependent on explicit alliances, but railier on standards — on 
just having Lliing.s in common. Ifs an unconscious union. This is 
impoiiant — it mean.s Jial a flow^ of ideas w ill happen even in the 
face of competition, lie<.:aLLse comp^iny A is laetter off if its software 
Ltnd hardware can Utlk to company H’s than if it can't, and vice versa. 
And it’.s just icing on tlie cake when they are enlightened enough to 
share implementations rather than just specifications — to realize 
that it’s to everyone’s advantage to just share the cotie rather titan 
wailing around for everyone else to reimplement it. Tills is wdiat tiic 
Open Source movement is all about, from a [>urely practical 
persf>ective at least, litis isn’t a completely new titing of cx)urse, hut 
it’s new that the Maemtosh will he luUy a part of this standards- 
Ixised, Unix-centered community, and it's new tliat this community 
w ill iitclude just aliout everyone “ and this is going to continue to 
[lush us forward as a whole. 


1984 Commercial 

<http://www.tbwachiat.eom/product/historicaLwork/tv/1984/1984, html> 

Apple's 1984: The Introduction of the Macintosh in the Cultural 
History of Personal Computers 

<http://www.duke, edu/'-tlove/mac.htm> 

So what does this all mean to the Macintosh developer? At the 
most obvious and literal level, it means tliat there’s a bunch of 
software out there which will suddenly run on Mac OS X with little 
or no modification, ranging from applications to frameworks to 
libraries to individual routines — things directly useful to the 
consumer, to the .system administrator, or to the developer. But 
more llindamentally, it means tliat tliere’s a new^ set of basics c>ul 
there -— a new range of technologies ihat every developer needs 
to know about. And really, it won’t be enough to just know that 
tliese leehnologies exist — developers will have to know' how^ to 
u.se them as a matter of course. And these New Basics are new in 
two ways: there are technologies which will lie new to Macintosh 
developers (and they may lie new to everyone), and it’s new that 
the essential basics are cross-platfomi — they’re the same for 
almost all developers, independent of operating system or type of 
development. So this montli, we’re going to touch on the first of 
these, XVIL, and point you to my picks for tlie essendal references. 
In the coming months, 1 hope to cover the rest of tlie New Basics. 
And when weYe done, pass the list on to your Unix and Windows 
friends — theyll need them too. 

By die way, you may be wondering why 1 singled out IBM 
to start off the discussion. They came to mind becau.se tlieir 
developerWorks site gives great coverage of the New Basics, and 
I’m constantly lead back to it. IBM has gone fr{>m a threat to a 
resource. Visit tlieir site frec|uendy to find ongoing information 
about important technologies. 

IBM developerWorks 

<htlp://wwvv.ibrn.conn/developer/> 

XML 

Tlie first New Basic is XML, As a technology, it lias been hyped, 
over-hyped, and reover-hyped in the press. It doesn’t solve every 
problem under the sun, as some liave implied, but it has done one 
important tiling: it has goEen everyone tliinking about information 
formats, and given us a common starting point to ftcxrk around when 
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designing new ways to store and interchange data, wliich makes it 
more likely tliiit die Ibrmats wn settle upon will he seasible Lind 
reascjnahly easy to prcx:ess by anyone who wants to. Ftjr Ix^Eer or 
worse, it is being used just about everywhere possible, and diis trend 
is only going to grow lor the foreseeable future. Developers will 
have to be comlbrtahle using it when reading and writing 
dtx:umenLs and when wanting applications which talk to other 
applioacions, either IcKally or over the intemei (which includes 
almost all application.s being w^ritten today). So here are my pick.s for 
the essentials: First, the annotated XML specification on XML.com, 
It's the specification itself with additional notes added by Tim l^ray, 
on of its autliors. It isn’t w^hat you’d w^ant to use to learn about XML 
for the very' first time, but it’s very' handy to have around when you 
need die final word on whedier some piece of syntax is legitimate, 
and it can be quicker to just go to die source rather dian searching 
for someone else’s explanation. But when youVe learning aliout 
XML as a develofier, you’re ultimately more interested in botv than 
what — you need to prcx:ess XML, ;ind die specification dt.jesn’t 
cover strategies for diis. Tlie tw'o l>^st restiun'es Tve found are 
lx)oks. Professional XAiL (ISBN: 1861003110) weighs in at over 1000 
pages, and it gives coverage to almost every major teclmology 
surrounding XML. Some of these tedinulogies liave evolved since 
the b<X)k was published almost a year ago, hut it’s still relevant to 
answer die ^^what’s diai^" and subsequent X>kay, now how do I use 
thaL^” questions. A newer reference is Essential XML 
(ISBN; 0201709147), It covers a nioie fixrussed range of topics, hut 
as a result it gives thorough coverage of all of the areas on which 
new^ technologies are likely to he built — methcxis for prcx:essing, 
specifying, navigating; linking, and transforming XML dcx:umenLs. 
And this book is refreshing and unique in two ways; For one, it 
focuses on the XML Information Set (InfoseO^ w'hich gives the 
abstract definition of XMI., independent of its syndetic detail, Tlie 
Lnfoset almost never gets coverage elsewhere, but ids really the mast 


impoitLint specific’atkxi, and it makes explicit die notion tliat whiii 
we nonnally diink of as XVIL is just one WLiy to write ii down on 
paper, just one syntax oul of many pcKsibilities for serializing XML 
data, tn the push for suindards, diis distinction is lietng iiverlooked, 
and there's an undue fix us on die synuix of XML over its concepts 
— people arc forgetting dial die angle brackeLs aren’t wdiat’s 
inifxirtant, and an alternative syntax might Ix' a gcxxi thing to liave 
around. Tile other refreshing diing alxiui Essimiial X\^fL is tliat it 
explicitly acknowledges that XML has been over-hyped, and in tad 
the authors w^nite it to help diem scin out w hat really is important to 
the progntmmer. 

Finally, my last essential reference for XML is the xmlhack web 
site. It's a news portal site, whidi gives summaries and links to 
relevant new^ bits of XML infonnation on the internet. Just glancing 
at it foim time to time will give you a feel for what areas are 
important uric] evolvuig, in addition to giving you pointers to new 
developments in technologies of specific interest. (I should mention 
trx) dial these pointers will sometimes lead you to the XML.coni site 
mentioned alxive, which is acaiaMy a great place to look for in<lepth 
articles.) 

The Annotated XML Specification 

<hltp:7/www.xml.com/pub/axml/a!(mlintro.html> 

xmlhack: developer news from the XML community 

<hltp://www.xmlhack.conn/> 

XML.com 

<http://www,xml.com/pub> 

So, that's it for the first of the New' BlisIcs. RememIxT to check 
biick in die coming months, when I hope to cover more of diem. 
Until then. I’ll keep you in suspense alxxii the rest of die 
technologies on my essentials list,.,. K1 
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statemenLs, and cc)irinienLs. Chapter 7 facusej^ on functioas, 
but contains some information on macn^s as well. Chapter 8 
shows how C++ programs can be modularized with the help 
of namespaces and intrcxluces exception fu:indling. Chapter 9, 
finally, is abcDut oiganizing C++ programs into files. 

All the chapters are rather terse with mostly tiny ccxle 
examples. (A notable exception is the desk-calculator 
example in tlie first section of the sixth chapter) Since the 
objective is to introduce language features, and not to teach 
how to prognim, I do not think that this is a problem. On the 
contiary, readers familiar with C-LLke syntax will appreciate 
StroustRjp’s style of quickly getting to the point. Otiiers 
should nor have any problems, either, even tliougli tliey 
naght need to read a seaion more tlian once in order to 
familiarize witli tlie C++ syntax. 

Abstraction Mechanis.ms 

The six chapters of part 11 descrilxi- die language 
constructs that support absuiia data types (ADTs), ul>jeci- 
oriented programming (OOP), and generic programming. 

Chapter 10 explains how ADTs can he defined that in 
their *1oc:)k-and-feef’ do not differ fn>m built-in ty'jxfs. Chapter 
11 complements chapter 10 by introducing operator 
overloading as well as friend functions ancl conversion 
operators. Both chapters lay the IViuncUition of the rest of the 
lx)ok, in particular of chaptei^ 12 and IS that treat C++'s 
support for OOP and also introduce the OOP vcxTahiikuy. 


Qiapter 13 and cliapter 14 cover templates and exception 
handling, respectively. 

These chapters are less terse, and the code 
examples are bigger as well. Readers with experience in 
OOP will again be happy with the pace. However, 1 am 
afraid that many OOP novices will need to look for a 
more gentle introduction to OOP, 

The Stanoaki> Librara^ 

The .seven chapters of part 01 present the standard 
library. Unlike the other four j^arts, I have not re-read tliis part 
for tliis review. (I liave read the Ixiok [albeit the 1st printing) 
in its entirety aix)ut tliree years ago and have used it as a 
reference manual ,sinee then.) 

But I rememlx^r that I load no dllTiculty to understand the 
oiganiziition and scanantics of tlie libraiy. Furtliemiore, 
whenever I look for a certain stream or ctinLdner, 1 quickly 
find it and am able to put it to gtxxl use in my ccxle. 

Design Using C++ 

The three cliupters of part IV, Di^vcdopment and 
Design, Design and Programming, and Roles of Classes, 
round off the book. 

This part cannot lie a replacement for a gcxxl software- 
engineering k>ok on. for instance, modeling, patterns, or 
ct )mponeni t >rientalic m. Nevertheless, Stn}ustmp's unique 
relation to G++ and his many years of experience as a 
.software de\elojXT pnivided liim with more tlian enougli 
valuable mLiterial and insights to share vvitli tlie readers. In my 
opinion, junior developers will profit mexst from tliis part, but 
it is definitely of interest to senior devekjpers as well. 

Conclusion 

In the course c]f tlie last five years, I have read 
cpiite a few hooks in the field of computer science 
engineering. Naturally, 1 encountered bad, good, and 
also some very good one.s. 

Bjarne Strouslrup’s Tbe C++ Programming 
Language is one of those very good lx>uks. It is 
crammed with useful information: to such an extent that 
— at lea.st in the beginning — one learns more about 
programming in general and about C++ in particular 
eveiy time one re-reads a section or a chapter. 

To cut a long story short. The C++ Programming 
Language is not only a must-read, it is a must-have for 
eveiy serious C++ programmer. 
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